REST API Guide: Complete Reference

By Orqestra · Published April 10, 2026 · Updated July 21, 2026

Orqestra provides a public REST API for integrating external systems. Use it to send messages, manage contacts, retrieve conversation data, and more.

This page covers the legacy v1 API. For new integrations, prefer API v2. Interactive Swagger documentation for v1 is available at /docs/api/v1.

Authentication

Every public API request requires a Bearer Token.

Authorization: Bearer wa_pk_xxxxxxxxxxxxxxxxxxxxxxxx

Create tokens under Settings > API Tokens. Give each token a recognizable name and revoke it at any time. Tokens begin with wa_pk_.

Keep tokens secret. An API token provides access to organization data. Never commit one to a public repository or expose it in frontend code. Rotate tokens regularly.

Base URL

https://orqestra.id/api/v1

Available Endpoints

Contacts

Create or update a contact

POST /contacts

Creates a contact or updates it when the WhatsApp number already exists.

Request body:

{
  "waId": "6281234567890",
  "name": "Budi Santoso",
  "email": "budi@example.com",
  "tags": ["vip-customer", "jakarta"]
}

Get a contact by number

GET /contacts/:waId

List contacts

GET /contacts?page=1&limit=50&tag=vip-customer

Messages

Send a text message

POST /messages/text

Request body:

{
  "waId": "6281234567890",
  "text": "Hello! We have processed your order #12345.",
  "channelId": "optional-channel-id"
}

This endpoint works only within 24 hours of the customer's last message. Outside that window, use the template endpoint.

Send a message template

POST /messages/template

Request body:

{
  "waId": "6281234567890",
  "templateName": "order_shipped",
  "languageCode": "id",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Budi" },
        { "type": "text", "text": "#12345" },
        { "type": "text", "text": "JNE REG" }
      ]
    }
  ]
}

Send an image

POST /messages/image

Request body:

{
  "waId": "6281234567890",
  "imageUrl": "https://cdn.example.com/product-image.jpg",
  "caption": "See our latest product."
}

Conversations

List conversations

GET /chats?status=open&page=1&limit=20

Optional parameters:

  • status — open, resolved, or all when omitted
  • channel — WHATSAPP or INSTAGRAM
  • channelId — Filter by a specific channel instance

Get conversation details

GET /chats/:chatId

Get message history

GET /chats/:chatId/messages?before=messageId&limit=50

Broadcasts

Create a broadcast

POST /broadcasts

Request body:

{
  "name": "May 2025 Promotion",
  "channelId": "channel-id",
  "templateName": "promo_may",
  "languageCode": "id",
  "recipients": [
    {
      "waId": "6281234567890",
      "variables": ["Budi", "PROMO25"]
    }
  ]
}

Get broadcast status

GET /broadcasts/:broadcastId

Response Format

Responses use a consistent JSON structure.

Success:

{
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 243
  }
}

Error:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "waId is required"
  }
}

HTTP Status Codes

CodeMeaning
200Successful request
201Resource created
400Invalid request, such as a missing field or incorrect format
401Missing or invalid token
403Token cannot access this resource
404Resource not found
422Validation failed with error details
429Rate limit exceeded
500Server error

Rate Limiting

Each token is limited to 60 requests per minute. When the limit is exceeded, the server returns HTTP 429 with these headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714000000

Wait until the timestamp in X-RateLimit-Reset before sending another request.

Outbound Webhooks

Orqestra can also send events to an external system through outbound webhooks.

Configure them under Settings > Outbound Webhooks. Available events include:

  • message.received — A new customer message arrived
  • message.sent — A message was sent successfully
  • chat.created — A new conversation was created
  • chat.assigned — A conversation was assigned to an agent
  • chat.resolved — A conversation was closed

Each event is sent as a POST request to the configured URL with an HMAC-SHA256 signature in the X-Webhook-Signature header.

SDKs and Libraries

Orqestra does not currently publish an official SDK. Use any standard HTTP library, including Node.js (axios, fetch), Python (httpx, requests), or PHP (Guzzle).

See Integration Examples in the documentation for language-specific examples.

Ready to build with Orqestra?

Start free or talk to our team about your integration.

Start FreeContact Us