One versioned surface
Public REST routes live under /v1. Compatibility routes under /api/v1 forward to the same API.
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.
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.
Public REST routes live under /v1. Compatibility routes under /api/v1 forward to the same API.
The API is the same production surface used by the dashboard, automations, AI replies, and journey sends.
Register one webhook endpoint and receive signed POSTs when customers reply or delivery state changes.
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.
curl https://api.instantreply.co/v1/conversations \
-H "Authorization: Bearer $IR_API_KEY"curl -X POST https://api.instantreply.co/v1/conversations/$ID/messages \
-H "Authorization: Bearer $IR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"Thanks for reaching out - how can we help?"}'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.
Failures return a JSON error envelope with code, message, doc_url, and request_id. Keep X-Request-Id from responses when asking support to trace a call.
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.
Read customer conversations, send replies, and sync message history.
/v1/conversationsList conversations with filters for status, channel, assignee, and cursor pagination.
/v1/conversations/:idRead one conversation with customer, channel, stage, tags, and latest activity.
/v1/conversations/:idUpdate assignment, status, tags, or routing fields for a conversation.
/v1/conversations/:id/messagesRead the message history for a conversation.
/v1/conversations/:id/messagesSend a reply on the correct WhatsApp, Instagram, or Messenger channel.
/v1/messagesList messages across conversations for audit, sync, or analytics jobs.
/v1/messagesCreate an outbound message when your integration already knows the channel context.
/v1/messages/:idFetch delivery and content details for one message.
Keep the customer record in sync and pull the operational metrics your app needs.
/v1/contactsList contacts with stage, score, owner, and channel identity.
/v1/contacts/:idRead a contact profile and linked conversation context.
/v1/contacts/:idUpdate contact fields created by lead capture or your CRM.
/v1/channelsList connected WhatsApp, Instagram, and Messenger channels.
/v1/analytics/summaryRead response-time, volume, and conversion summary metrics.
/v1/usageRead plan usage for messages, AI replies, webhooks, and API calls.
Manage API keys and subscribe your server to signed, real-time events.
/v1/keysList active API keys and scopes.
/v1/keysCreate a scoped key for a backend, agent, or test environment.
/v1/keys/:id/rotateRotate a key without downtime.
/v1/keys/:idRevoke a key immediately.
/v1/webhooksList webhook endpoints.
/v1/webhooksRegister a signed webhook endpoint.
/v1/webhooks/:idDisable a webhook endpoint.
/v1/webhooks/:id/deliveriesInspect recent delivery attempts and failures.
Trigger WhatsApp journeys, inspect delivery outcomes, and sync business events.
/v1/journeysList journey templates available to your account.
/v1/triggerEnroll a contact into a journey or template workflow.
/v1/trigger/status/:idExplain the current delivery result for a trigger.
/v1/trigger/historyReview recent trigger activity.
/v1/trigger/validateValidate a trigger payload before sending.
/v1/trigger/batchTrigger a batch of contacts with per-row results.
/v1/trigger/enrollmentsCancel active enrollments for a contact or journey.
/v1/eventsSend an external business event into InstantReply.
/v1/campaigns/:id/sendStart an approved campaign send.
Validate, submit, and debug WhatsApp templates without guessing Meta policy behavior.
/v1/templatesList templates and status from InstantReply and Meta.
/v1/templatesCreate a template draft.
/v1/templates/:idRead a template with category and provider status.
/v1/templates/generate/validateValidate generated copy before saving it.
/v1/templates/:id/validateCheck category fit and get UTILITY coaching.
/v1/templates/:id/submitSubmit the template to Meta for review.
/v1/developer/capabilitiesRead scopes, enabled features, and integration limits.
/v1/developer/troubleshooting/errors/:codeLook up a known provider error.
Move leads, trigger automations, and reply to supported social comments.
/v1/pipeline/leadsList leads in the sales pipeline.
/v1/pipeline/leads/:idRead one lead with stage and conversation context.
/v1/pipeline/leads/:idUpdate lead fields from your CRM or app.
/v1/pipeline/leads/:id/stageMove a lead to a new stage.
/v1/pipeline/stagesList configured pipeline stages.
/v1/automationsList available automations.
/v1/automations/:id/triggerTrigger an automation explicitly.
/v1/comments/:id/replyReply to a supported social comment.
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.
Each webhook has a whsec_ signing secret. Verify X-InstantReply-Signature with HMAC-SHA256 over timestamp.rawBody before trusting the payload. Recent attempts are available at GET /v1/webhooks/:id/deliveries.
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")
verifyHmacSha256({
secret: process.env.IR_WEBHOOK_SECRET,
payload: timestamp + "." + rawBody,
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. |
template.status_update | Meta reports a template review or quality status change. |
message.delivery_failed | A provider rejects or fails delivery after retries. |
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.
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.
A production integration is ready when these are true.