v1 · 22 endpoints · 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.
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
Twenty-two endpoints, 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/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/webhooksList registered webhook endpoints - POST
/v1/webhooksRegister a webhook, returns signing secret - DELETE
/v1/webhooks/:idRevoke a webhook endpoint - GET
/v1/templatesList WhatsApp message templates - GET
/v1/templates/:idFetch one template - 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/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.
// 422 Unprocessable Entity
{
"error": {
"code": "INVALID_PLATFORM",
"message": "Channel 'tiktok' is not yet supported on v1.",
"doc_url": "https://www.instantreply.co/api-docs#errors",
"request_id": "req_8f2a0b1c"
}
}