First call,
five minutes.
Generate a key, list conversations, send a reply, register a webhook. No SDK install required. SDKs are sugar.
01
Create an API key
Open Settings → API Keys, click New key, give it a label, pick scopes. Copy once. Keys starting with ir_live_ deliver real messages. Keys starting with ir_test_ never do.
# .env
IR_API_KEY=ir_live_3f2a...02
List your conversations
Every list endpoint is cursor-paginated. Pass ?cursor= for the next page. Max 100 per call.
curl https://api.instantreply.co/v1/conversations \
-H "Authorization: Bearer $IR_API_KEY"03
Send a reply
POST a message to a conversation. With a test key the call returns a fake 201 and never touches Meta. With a live key the platform handles delivery, retries, and platform compliance.
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." }'04
Trigger a WhatsApp Journey
The Journey Trigger API sends pre-approved WhatsApp template messages to any phone number. List available journeys with GET /api/v1/journeys to see required variables, then trigger with a single POST. Track delivery via the status_url in the response. See the Developer Hub for an interactive playground.
# List available journeys and their required variables
curl https://api.instantreply.co/api/v1/journeys \
-H "Authorization: Bearer $IR_API_KEY"
# Trigger a journey
curl -X POST https://api.instantreply.co/api/v1/trigger \
-H "Authorization: Bearer $IR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"trigger_name": "drjob_shortlisted",
"phone": "+971501234567",
"metadata": { "1": "Ahmed", "2": "Senior Accountant", "3": "https://drjob.ae/app/8123" }
}'05
Register a webhook
The response includes a signing secret (whsec_...). Verify the X-IR-Signature header on every incoming payload. Failed deliveries retry on an exponential backoff for 30 days.
curl -X POST https://api.instantreply.co/v1/webhooks \
-H "Authorization: Bearer $IR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourapp.com/webhooks/ir",
"events": ["message.received", "conversation.closed"]
}'06
Validate and submit a WhatsApp template
Before sending a template to Meta, validate it. The response tells you the policy risk level and whether the template qualifies as UTILITY (roughly 66% cheaper than MARKETING). If it does not qualify, the utility_coaching field lists the phrases to change. Submit once it is clean.
# Validate a stored template before submitting to Meta
curl -X POST https://api.instantreply.co/v1/templates/$TEMPLATE_ID/validate \
-H "Authorization: Bearer $IR_API_KEY"
# 200 — example response
# {
# "validation_status": "ok",
# "proposed_category": "UTILITY",
# "policy_risk": "low",
# "utility_coaching": {
# "flagged_phrases": [],
# "qualifies_as_utility": true,
# "estimated_saving_pct": 66
# }
# }
# Submit once it's clean
curl -X POST https://api.instantreply.co/v1/templates/$TEMPLATE_ID/submit \
-H "Authorization: Bearer $IR_API_KEY"07
Debug a delivery failure
When a message does not arrive, use GET /v1/trigger/status/:id to get a plain-English explanation: what failed, whether it is a platform or Meta issue, and the next safe step. You can also look up any Meta error code directly.
# Explain a delivery failure for a specific trigger run
curl https://api.instantreply.co/v1/trigger/status/$AUTOMATION_ACTION_ID \
-H "Authorization: Bearer $IR_API_KEY"
# Or look up a known Meta error code
curl https://api.instantreply.co/v1/developer/troubleshooting/errors/131049 \
-H "Authorization: Bearer $IR_API_KEY"
# 200 — example response
# {
# "code": "131049",
# "what_happened": "Meta throttled the marketing template for this contact.",
# "fault": "meta",
# "next_step": "Wait 24 h or switch to a UTILITY template.",
# "retryable": false
# }Next