v1 - core routes - api.instantreply.co

WhatsApp + Instagram
REST API, v1.

Bearer auth. Cursor pagination. Idempotency keys. Signed webhooks. The API your team would have built if it had the weekend.

Live reference Five-minute quickstart →

Pick a runtime

const API_BASE = process.env.IR_API_URL ?? 'https://api.instantreply.co';
const headers = { 'Authorization': `Bearer ${process.env.IR_API_KEY}` };

// List active conversations
const res = await fetch(`${API_BASE}/v1/conversations?status=active`, { headers });
const { data, pagination } = await res.json();

for (const c of data) {
  if (c.last_message_preview?.includes('refund')) {
    await fetch(`${API_BASE}/v1/conversations/${c.id}`, {
      method: 'PATCH', headers: { ...headers, 'Content-Type': 'application/json' },
      body: JSON.stringify({ tags: ['priority:refund'] }),
    });
  }
}

v1 surface

Core routes, one auth header.

GET/v1/conversationsList conversations, cursor pagination
GET/v1/conversations/:idFetch one conversation
PATCH/v1/conversations/:idUpdate status, assignee, tags
GET/v1/conversations/:id/messagesList messages in a conversation
POST/v1/conversations/:id/messagesSend an outbound reply
GET/v1/messagesList sent and received messages with delivery status
POST/v1/messagesSend a message by conversation or contact
GET/v1/messages/:idFetch one message with delivery status
GET/v1/contactsList contacts
GET/v1/contacts/:idFetch one contact
PATCH/v1/contacts/:idUpdate name, email, lead stage
GET/v1/channelsConnected platforms, status
GET/v1/analytics/summaryDashboard analytics by date range
GET/v1/usageTier, rate-limit headroom, request count
GET/v1/keysList API keys for the workspace
POST/v1/keysCreate a scoped live or test key
POST/v1/keys/:id/rotateRotate an API key
DELETE/v1/keys/:idRevoke an API key
GET/v1/webhooksList registered webhook endpoints
POST/v1/webhooksRegister a webhook, returns signing secret
DELETE/v1/webhooks/:idRevoke a webhook endpoint
GET/v1/webhooks/:id/deliveriesInspect recent webhook delivery attempts
POST/v1/webhooks/sendTrigger a WhatsApp journey/send immediately
POST/v1/webhooks/trigger-campaignCompatibility alias for /v1/webhooks/send
POST/v1/webhooks/sign-payloadGenerate a test HMAC signature for a payload
GET/v1/journeysList active WhatsApp journeys and required variables
POST/v1/triggerEnroll a phone into a WhatsApp journey
GET/v1/trigger/historyList recent journey trigger enrollments
POST/v1/trigger/validateDry-run a journey trigger payload
POST/v1/trigger/batchBatch enroll up to 100 recipients
DELETE/v1/trigger/enrollmentsStop enrollments for a phone/journey
POST/v1/eventsFire a semantic event mapped to a journey
GET/v1/templatesList WhatsApp message templates
POST/v1/templatesCreate and submit a template to Meta
GET/v1/templates/:idFetch one template
POST/v1/templates/generate/validateValidate a draft objective before storing
POST/v1/templates/:id/validateValidate category fit + UTILITY coaching (flagged phrases, cost gap)
POST/v1/templates/:id/submitSubmit template to Meta for approval
GET/v1/trigger/status/:idExplain a delivery outcome - what happened, fault (ours vs Meta), next step
GET/v1/campaignsList broadcast campaigns
POST/v1/campaignsCreate a campaign draft
GET/v1/campaigns/:idFetch one campaign
PATCH/v1/campaigns/:idUpdate a draft or scheduled campaign
POST/v1/campaigns/:id/sendStart a draft campaign
GET/v1/pipeline/leadsList pipeline leads
GET/v1/pipeline/leads/:idFetch one pipeline lead
PATCH/v1/pipeline/leads/:idUpdate pipeline lead fields
PATCH/v1/pipeline/leads/:id/stageMove a lead to a new stage
GET/v1/pipeline/stagesList pipeline stages
GET/v1/automationsList automations
GET/v1/automations/:idFetch one automation
POST/v1/automations/:id/triggerManually trigger an automation
GET/v1/commentsList tracked comments
GET/v1/comments/:idFetch one comment
POST/v1/comments/:id/replyReply to a tracked comment
GET/v1/developer/capabilitiesScopes and features available to the current key
GET/v1/developer/onboardingIntegration checklist - which steps are done
GET/v1/developer/limitsRate limits and quotas for the current plan tier
GET/v1/developer/troubleshooting/errors/:codePlain-English explanation of a Meta or platform error code

Design

Boring choices, on purpose.

01
Cursor pagination, always
Every list endpoint returns has_more and next_cursor. No skipped records under load, no off-by-one.
02
Idempotency-Key on POST
Pass a UUID and retry safely for 24 hours. Side effects fire exactly once.
03
X-Request-Id on every reply
Paste the ID in support and we trace the exact request, exact response, exact downstream call.
04
Errors with shape
Same JSON envelope on every failure. code, message, doc_url, request_id. No surprise nulls.

Errors

One envelope, every time.

No nested success flags. No mixed casing. No silent 200s on failure. If the call broke, the body tells you exactly which call, what it expected, and where the docs live.

error.jsonjson

// 422 Unprocessable Entity
{
  "error": {
    "code": "INVALID_PLATFORM",
    "message": "Channel 'tiktok' is not yet supported on v1.",
    "doc_url": "https://instantreply.co/api-docs#errors",
    "request_id": "req_8f2a0b1c"
  }
}

No card on the trial

Open the reference. Call the API with your key.

Open reference Generate API key →

v1 - core routes - api.instantreply.co

WhatsApp + Instagram
REST API, v1.

Bearer auth. Cursor pagination. Idempotency keys. Signed webhooks. The API your team would have built if it had the weekend.

Live reference Five-minute quickstart →

Pick a runtime

const API_BASE = process.env.IR_API_URL ?? 'https://api.instantreply.co';
const headers = { 'Authorization': `Bearer ${process.env.IR_API_KEY}` };

// List active conversations
const res = await fetch(`${API_BASE}/v1/conversations?status=active`, { headers });
const { data, pagination } = await res.json();

for (const c of data) {
  if (c.last_message_preview?.includes('refund')) {
    await fetch(`${API_BASE}/v1/conversations/${c.id}`, {
      method: 'PATCH', headers: { ...headers, 'Content-Type': 'application/json' },
      body: JSON.stringify({ tags: ['priority:refund'] }),
    });
  }
}

v1 surface

Core routes, one auth header.

GET/v1/conversationsList conversations, cursor pagination
GET/v1/conversations/:idFetch one conversation
PATCH/v1/conversations/:idUpdate status, assignee, tags
GET/v1/conversations/:id/messagesList messages in a conversation
POST/v1/conversations/:id/messagesSend an outbound reply
GET/v1/messagesList sent and received messages with delivery status
POST/v1/messagesSend a message by conversation or contact
GET/v1/messages/:idFetch one message with delivery status
GET/v1/contactsList contacts
GET/v1/contacts/:idFetch one contact
PATCH/v1/contacts/:idUpdate name, email, lead stage
GET/v1/channelsConnected platforms, status
GET/v1/analytics/summaryDashboard analytics by date range
GET/v1/usageTier, rate-limit headroom, request count
GET/v1/keysList API keys for the workspace
POST/v1/keysCreate a scoped live or test key
POST/v1/keys/:id/rotateRotate an API key
DELETE/v1/keys/:idRevoke an API key
GET/v1/webhooksList registered webhook endpoints
POST/v1/webhooksRegister a webhook, returns signing secret
DELETE/v1/webhooks/:idRevoke a webhook endpoint
GET/v1/webhooks/:id/deliveriesInspect recent webhook delivery attempts
POST/v1/webhooks/sendTrigger a WhatsApp journey/send immediately
POST/v1/webhooks/trigger-campaignCompatibility alias for /v1/webhooks/send
POST/v1/webhooks/sign-payloadGenerate a test HMAC signature for a payload
GET/v1/journeysList active WhatsApp journeys and required variables
POST/v1/triggerEnroll a phone into a WhatsApp journey
GET/v1/trigger/historyList recent journey trigger enrollments
POST/v1/trigger/validateDry-run a journey trigger payload
POST/v1/trigger/batchBatch enroll up to 100 recipients
DELETE/v1/trigger/enrollmentsStop enrollments for a phone/journey
POST/v1/eventsFire a semantic event mapped to a journey
GET/v1/templatesList WhatsApp message templates
POST/v1/templatesCreate and submit a template to Meta
GET/v1/templates/:idFetch one template
POST/v1/templates/generate/validateValidate a draft objective before storing
POST/v1/templates/:id/validateValidate category fit + UTILITY coaching (flagged phrases, cost gap)
POST/v1/templates/:id/submitSubmit template to Meta for approval
GET/v1/trigger/status/:idExplain a delivery outcome - what happened, fault (ours vs Meta), next step
GET/v1/campaignsList broadcast campaigns
POST/v1/campaignsCreate a campaign draft
GET/v1/campaigns/:idFetch one campaign
PATCH/v1/campaigns/:idUpdate a draft or scheduled campaign
POST/v1/campaigns/:id/sendStart a draft campaign
GET/v1/pipeline/leadsList pipeline leads
GET/v1/pipeline/leads/:idFetch one pipeline lead
PATCH/v1/pipeline/leads/:idUpdate pipeline lead fields
PATCH/v1/pipeline/leads/:id/stageMove a lead to a new stage
GET/v1/pipeline/stagesList pipeline stages
GET/v1/automationsList automations
GET/v1/automations/:idFetch one automation
POST/v1/automations/:id/triggerManually trigger an automation
GET/v1/commentsList tracked comments
GET/v1/comments/:idFetch one comment
POST/v1/comments/:id/replyReply to a tracked comment
GET/v1/developer/capabilitiesScopes and features available to the current key
GET/v1/developer/onboardingIntegration checklist - which steps are done
GET/v1/developer/limitsRate limits and quotas for the current plan tier
GET/v1/developer/troubleshooting/errors/:codePlain-English explanation of a Meta or platform error code

Design

Boring choices, on purpose.

01
Cursor pagination, always
Every list endpoint returns has_more and next_cursor. No skipped records under load, no off-by-one.
02
Idempotency-Key on POST
Pass a UUID and retry safely for 24 hours. Side effects fire exactly once.
03
X-Request-Id on every reply
Paste the ID in support and we trace the exact request, exact response, exact downstream call.
04
Errors with shape
Same JSON envelope on every failure. code, message, doc_url, request_id. No surprise nulls.

Errors

One envelope, every time.

No nested success flags. No mixed casing. No silent 200s on failure. If the call broke, the body tells you exactly which call, what it expected, and where the docs live.

error.jsonjson

// 422 Unprocessable Entity
{
  "error": {
    "code": "INVALID_PLATFORM",
    "message": "Channel 'tiktok' is not yet supported on v1.",
    "doc_url": "https://instantreply.co/api-docs#errors",
    "request_id": "req_8f2a0b1c"
  }
}

No card on the trial

Open the reference. Call the API with your key.

Open reference Generate API key →

WhatsApp + InstagramREST API, v1.

Core routes, one auth header.

Boring choices, on purpose.

Cursor pagination, always

Idempotency-Key on POST

X-Request-Id on every reply

Errors with shape

One envelope, every time.

Open the reference. Call the API with your key.

WhatsApp + InstagramREST API, v1.

Core routes, one auth header.

Boring choices, on purpose.

Cursor pagination, always

Idempotency-Key on POST

X-Request-Id on every reply

Errors with shape

One envelope, every time.

Open the reference. Call the API with your key.

WhatsApp + Instagram
REST API, v1.

WhatsApp + Instagram
REST API, v1.