v1 production reference

InstantReply API Reference

Build against the production REST API for WhatsApp, Instagram, and Messenger conversations. Auth, pagination, messages, journeys, templates, signed webhooks, delivery debugging, and developer endpoints are all here.

Start quickstart Endpoint catalog Developer hub

What a developer can build

Use InstantReply as the messaging layer for your product or internal tools. Your backend can read conversations, send replies, update contacts, route leads, trigger WhatsApp journeys, validate templates, and react to customer messages in real time.

One versioned surface

Public REST routes live under /v1. Compatibility routes under /api/v1 forward to the same API.

Works with real operations

The API is the same production surface used by the dashboard, automations, AI replies, and journey sends.

No polling needed

Authentication, pagination, and errors

Authenticate with a scoped API key in Authorization: Bearer $IR_API_KEY. Keep live and test keys separate. Rotate keys from the developer settings without changing your webhook signing secret.

authbash

curl https://api.instantreply.co/v1/conversations \
  -H "Authorization: Bearer $IR_API_KEY"

send-messagebash

curl -X POST https://api.instantreply.co/v1/conversations/$ID/messages \
  -H "Authorization: Bearer $IR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Thanks for reaching out - how can we help?"}'

Cursor pagination

Every list endpoint accepts ?cursor= and returns the next cursor when more records exist. Keep the cursor opaque and pass it back exactly as received.

Predictable errors

Responses include X-Request-ID for correlation; you may provide a valid ID or let the API generate one. POST /v1/messages and POST /v1/conversations/:id/messages require Idempotency-Key: an identical retry replays its result, while a different body with the same key returns 409. Other send routes do not necessarily support this header. Use GET /v1/messages or GET /v1/trigger/status/:id to inspect delivery status. GET /v1/status is an unauthenticated database/Redis dependency health check (200 healthy, 503 degraded); request trace fields are internal and there is no public trace lookup endpoint. Sending: a send returns 201 only when it was really sent; if the provider rejects it the response is 422 SEND_FAILED. Free text on WhatsApp requires an open customer-service window; outside it, send an approved template with POST /v1/templates/:id/send. A replayed Idempotency-Key response carries Idempotent-Replayed: true. Per-number sending: the templates endpoint resolves the sender as explicit integration_id, then the template's pinned number, then the workspace's single active WhatsApp number, else 409 AMBIGUOUS_INTEGRATION. Scopes: messages:send for free-text sends, templates:send for template sends, automations:write for per-channel DM/comment toggles and comment rules. Set integration_id on a comment trigger rule to scope it to one connected Instagram/Facebook page. Rate limits are per key per minute by plan tier: 30 free, 120 dev_hobby/starter, 600 trial/dev_pro/growth, 2400 dev_scale/pro, 10000 enterprise; GET /v1/developer/limits returns your key's value.

Production endpoint groups

These are the routes developers use most often. The complete route inventory is in the REST endpoint catalog, but this page explains what each group is for and how it fits into an integration.

Open full REST endpoint catalog

Conversations and messages

Read customer conversations, send replies, and sync message history.

GET/v1/conversations
List conversations with filters for status, channel, assignee, and cursor pagination.
GET/v1/conversations/:id
Read one conversation with customer, channel, stage, tags, and latest activity.
PATCH/v1/conversations/:id
Update assignment, status, tags, or routing fields for a conversation.
GET/v1/conversations/:id/messages
Read the message history for a conversation.
POST/v1/conversations/:id/messages
Send a reply on the conversation's channel with messages:send and a required Idempotency-Key header. Optional integration_id must match the conversation's connected account or returns 409 ACCOUNT_MISMATCH.
GET/v1/messages
List messages across conversations for audit, sync, or analytics jobs.
POST/v1/messages
Send free-form content (1–4096 characters) with messages:send and a required Idempotency-Key header. Use conversation_id, or contact_id plus channel for an existing conversation. Optional integration_id selects the connected account; use GET /v1/channels. Ambiguous contact chats return 409 ACCOUNT_REQUIRED.
GET/v1/messages/:id
Fetch delivery and content details for one message.

Support tickets

Sync the human-work queue InstantReply creates from handoffs, safety reviews, and routing rules.

GET/v1/tickets
List tickets by status, priority, kind, assignee, or conversation with stable cursor pagination.
GET/v1/tickets/:id
Read one ticket with lifecycle, SLA, assignment, and conversation references.
PATCH/v1/tickets/:id
Update status, priority, or assignee with optional optimistic concurrency.

Contacts, channels, and analytics

Keep the customer record in sync and pull the operational metrics your app needs.

GET/v1/contacts
List contacts with stage, score, owner, and channel identity.
GET/v1/contacts/:id
Read a contact profile and linked conversation context.
PATCH/v1/contacts/:id
Update contact fields created by lead capture or your CRM.
GET/v1/channels
List connected WhatsApp, Instagram, and Messenger channels.
PATCH/v1/channels/:integration_id
Set DM replies with { ai_enabled } or Instagram/Facebook comment replies with { ai_comment_replies_enabled } for only this connected account; requires automations:write.
GET/v1/analytics/summary
Read response-time, volume, and conversion summary metrics.
GET/v1/usage
Read plan usage for messages, AI replies, webhooks, and API calls.
GET/v1/status
Unauthenticated database/Redis dependency health. Returns 200 when healthy, 503 when degraded, and error_rate: null until enough real usage history exists.

Keys and webhooks

Manage API keys and subscribe your server to signed, real-time events.

GET/v1/keys
List active API keys and scopes.
POST/v1/keys
Create a scoped key for a backend, agent, or test environment.
POST/v1/keys/:id/rotate
Rotate a key without downtime.
DELETE/v1/keys/:id
Revoke a key immediately.
GET/v1/webhooks
List webhook endpoints.
POST/v1/webhooks
Register a signed webhook endpoint.
DELETE/v1/webhooks/:id
Disable a webhook endpoint.
GET/v1/webhooks/:id/deliveries
Inspect recent delivery attempts and failures.
POST/v1/webhooks/send
Trigger an immediate WhatsApp journey/send.
POST/v1/webhooks/trigger-campaign
Compatibility alias for the immediate send endpoint.
POST/v1/webhooks/sign-payload
Generate a test HMAC signature for webhook verification.

Journeys, triggers, and campaigns

Trigger WhatsApp journeys, inspect delivery outcomes, and sync business events.

GET/v1/journeys
List journey templates available to your account.
POST/v1/journeys
Create a journey and map approved WhatsApp templates to its steps.
GET/v1/journeys/:id
Read one journey with its mapped templates and step delays.
PUT/v1/journeys/:id/steps
Replace the journey step map with organization-owned templates.
PATCH/v1/journeys/:id/status
Activate or pause a journey after its template mapping is ready.
POST/v1/trigger
Enroll a contact into a journey or template workflow.
GET/v1/trigger/limits
Read journey quota, usage, and remaining capacity.
GET/v1/trigger/status/:id
Explain the current delivery result for a trigger.
GET/v1/trigger/history
Review recent trigger activity.
POST/v1/trigger/validate
Validate a trigger payload before sending.
POST/v1/trigger/batch
Trigger a batch of contacts with per-row results.
DELETE/v1/trigger/enrollments
Cancel active enrollments for a contact or journey.
POST/v1/events
Send an external business event into InstantReply.
GET/v1/campaigns
List broadcast campaigns.
POST/v1/campaigns
Create a campaign draft.
GET/v1/campaigns/:id
Read one campaign.
PATCH/v1/campaigns/:id
Update a draft or scheduled campaign.
POST/v1/campaigns/:id/send
Start an approved campaign send.

Support tickets

Sync the human-work queue InstantReply creates from handoffs, safety reviews, and routing rules.

GET/v1/tickets
List tickets with status, priority, assignee, conversation, and cursor filters.
GET/v1/tickets/:id
Read one ticket with lifecycle, SLA, assignment, and conversation references.
PATCH/v1/tickets/:id
Update ticket status, priority, assignee, or resolution metadata.

Templates and developer tools

Validate, submit, and debug WhatsApp templates without guessing Meta policy behavior.

GET/v1/templates
List templates and status from InstantReply and Meta.
POST/v1/templates
Create a template draft.
GET/v1/templates/:id
Read a template with category and provider status.
POST/v1/templates/:id/send
Send an approved template using templates:send. Optional integration_id selects the sender; otherwise the pinned template number or sole active number is used. Multiple unresolved active numbers return 409 AMBIGUOUS_INTEGRATION.
DELETE/v1/templates/:id
Delete a template from Meta and the local registry.
POST/v1/templates/generate/validate
Validate generated copy before saving it.
POST/v1/templates/:id/validate
Check category fit and get UTILITY coaching.
POST/v1/templates/:id/submit
Submit the template to Meta for review.
GET/v1/developer/capabilities
Read scopes, enabled features, and integration limits.
GET/v1/developer/onboarding
Read the integration checklist and setup state.
GET/v1/developer/limits
Read rate limits and plan quotas.
GET/v1/developer/troubleshooting/errors/:code
Look up a known provider error.

Pipeline and automations

Move leads, trigger automations, and reply to supported social comments.

GET/v1/pipeline/leads
List leads in the sales pipeline.
GET/v1/pipeline/leads/:id
Read one lead with stage and conversation context.
PATCH/v1/pipeline/leads/:id
Update lead fields from your CRM or app.
PATCH/v1/pipeline/leads/:id/stage
Move a lead to a new stage.
GET/v1/pipeline/stages
List configured pipeline stages.
GET/v1/automations
List available automations.
GET/v1/automations/:id
Read one automation.
POST/v1/automations/:id/trigger
Trigger an automation explicitly.
GET/v1/comments
List tracked social comments.
GET/v1/comments/:id
Read one tracked social comment.
POST/v1/comments/:id/reply
Reply to a supported social comment.
GET/v1/comments/settings
Read comment automation switches and keyword rules.
PATCH/v1/comments/settings
Update org-wide comment settings and rules. Add integration_id to a trigger rule to scope it to one connected page; requires automations:write.

Webhooks and security

Register POST /v1/webhooks once and InstantReply will push real-time events to your server. Deliveries are at least once, so process X-InstantReply-Delivery idempotently.

1. Create a public HTTPS endpoint

Your endpoint must accept POST JSON and return any 2xx status within 8 seconds. For local testing, expose localhost with a tunnel such as ngrok or Cloudflare Tunnel.

2. Register the endpoint

Call POST /v1/webhooks with a scoped key that has webhooks:write. Subscribe to exact events, *, or namespace wildcards such as message.*, conversation.*, contact.*, ticket.*, or template.*.

3. Store the secret and inspect attempts

The response returns a whsec_ secret once. Store it immediately, verify every delivery, and use GET /v1/webhooks/:id/deliveries to debug status codes, retries, and failures.

Signature verification

Registering a webhook returns its whsec_ signing secret once, in that response body only — store it immediately; it is never shown again. Lost it? Delete the endpoint and register a new one. Verify X-InstantReply-Signature, formatted as sha256=<hex>, with HMAC-SHA256 over {timestamp}.{rawBody} before trusting the payload. Recent attempts are available at GET /v1/webhooks/:id/deliveries.

verify-signaturets

app.post("/webhooks/instantreply", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("X-InstantReply-Timestamp")
  const signature = req.header("X-InstantReply-Signature")
  const rawBody = req.body.toString("utf8")
  const signedPayload = timestamp + "." + rawBody

  verifyHmacSha256(process.env.IR_WEBHOOK_SECRET, signedPayload, signature)

  res.sendStatus(204)
})

Current event names
Event	Fires when
`message.received`	A customer sends a WhatsApp, Instagram, or Messenger message.
`message.sent`	An outbound message lands from AI, dashboard, API, automation, or journey.
`conversation.created`	A new conversation opens from inbound traffic, coexistence, or a journey.
`conversation.closed`	A conversation is resolved manually or by automation.
`conversation.assigned`	Ownership changes by manual assignment or routing rules.
`contact.updated`	Lead extraction or CRM sync updates a contact.
`contact.opted_out`	A contact opts out, for example by replying STOP, so your CRM can suppress them.
`contact.opted_in`	A previously opted-out contact opts back in, for example by replying START.
`template.status_update`	Meta reports a template review or quality status change.
`message.delivery_failed`	A provider rejects or fails delivery after retries.
`ticket.created`	InstantReply creates a support ticket from a handoff or review.
`ticket.updated`	Ticket status, priority, or assignment data changes.
`ticket.assigned`	Ticket ownership changes.
`ticket.closed`	A support ticket is resolved.

Template lifecycle and delivery debugging

Template endpoints help teams ship compliant WhatsApp templates. Validate category fit, submit to Meta, inspect provider outcomes, and explain known delivery errors before a marketer has to guess.

POST /v1/templates/:id/validate checks category fit and gives UTILITY coaching.
POST /v1/templates/:id/submit routes the template to Meta review.
GET /v1/trigger/status/:id explains delivery outcomes for journey triggers.
GET /v1/developer/onboarding and /limits show setup state, plan features, quotas, and rate limits.

Generated OpenAPI in production

Generated Swagger/OpenAPI output is available in non-production environments for internal validation. Production intentionally does not expose /openapi.json. Use this reference, the REST catalog, and the quickstart as the public developer surface.

Ship checklist

A production integration is ready when these are true.

Use https://api.instantreply.co/v1 in production.

Store live and test API keys separately.

Verify X-InstantReply-Signature before accepting a webhook.

Handle duplicate webhook deliveries with X-InstantReply-Delivery.

Retry POST requests only with an idempotency strategy.

Respect channel messaging windows and opt-outs.

curl -X POST https://api.instantreply.co/v1/conversations/$ID/messages \ -H "Authorization: Bearer $IR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"content":"Thanks for reaching out - how can we help?"}'

Journeys, triggers, and campaigns

Trigger WhatsApp journeys, inspect delivery outcomes, and sync business events.

GET/v1/journeys
List journey templates available to your account.
POST/v1/journeys
Create a journey and map approved WhatsApp templates to its steps.
GET/v1/journeys/:id
Read one journey with its mapped templates and step delays.
PUT/v1/journeys/:id/steps
Replace the journey step map with organization-owned templates.
PATCH/v1/journeys/:id/status
Activate or pause a journey after its template mapping is ready.
POST/v1/trigger
Enroll a contact into a journey or template workflow.
GET/v1/trigger/limits
Read journey quota, usage, and remaining capacity.
GET/v1/trigger/status/:id
Explain the current delivery result for a trigger.
GET/v1/trigger/history
Review recent trigger activity.
POST/v1/trigger/validate
Validate a trigger payload before sending.
POST/v1/trigger/batch
Trigger a batch of contacts with per-row results.
DELETE/v1/trigger/enrollments
Cancel active enrollments for a contact or journey.
POST/v1/events
Send an external business event into InstantReply.
GET/v1/campaigns
List broadcast campaigns.
POST/v1/campaigns
Create a campaign draft.
GET/v1/campaigns/:id
Read one campaign.
PATCH/v1/campaigns/:id
Update a draft or scheduled campaign.
POST/v1/campaigns/:id/send
Start an approved campaign send.

app.post("/webhooks/instantreply", express.raw({ type: "application/json" }), (req, res) => { const timestamp = req.header("X-InstantReply-Timestamp") const signature = req.header("X-InstantReply-Signature") const rawBody = req.body.toString("utf8") const signedPayload = timestamp + "." + rawBody verifyHmacSha256(process.env.IR_WEBHOOK_SECRET, signedPayload, signature) res.sendStatus(204) })

Event

Fires when

message.received

A customer sends a WhatsApp, Instagram, or Messenger message.

message.sent

An outbound message lands from AI, dashboard, API, automation, or journey.

conversation.created

A new conversation opens from inbound traffic, coexistence, or a journey.

conversation.closed

A conversation is resolved manually or by automation.

conversation.assigned

Ownership changes by manual assignment or routing rules.

contact.updated

Lead extraction or CRM sync updates a contact.

contact.opted_out

A contact opts out, for example by replying STOP, so your CRM can suppress them.

contact.opted_in

A previously opted-out contact opts back in, for example by replying START.

template.status_update

Meta reports a template review or quality status change.

message.delivery_failed

A provider rejects or fails delivery after retries.

ticket.created

InstantReply creates a support ticket from a handoff or review.

ticket.updated

Ticket status, priority, or assignment data changes.

ticket.assigned

Ticket ownership changes.

ticket.closed

A support ticket is resolved.