The Unecast REST API gives developers full programmatic access to Unecast’s messaging, contact management, and automation capabilities. Use it to build custom integrations with internal systems, extend Unecast into your own product, or automate complex workflows that go beyond what no-code tools can handle. Every capability available in the Unecast UI - sending WhatsApp messages, creating contacts, triggering automations - is accessible through the API.

Authentication

The Unecast API uses Bearer token authentication. Every request must include your API key in the Authorization header. Generate your API key in Settings → API → Generate API Key. Treat your API key like a password - do not expose it in client-side code or public repositories.

curl -X GET "https://flow.unecast.com/api/v1/account" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID"

Core Capabilities

Send Messages

Send WhatsApp messages, SMS, and other channel messages to any contact. Use pre-approved WhatsApp templates for business-initiated outreach.

Manage Contacts

Create, read, update, and delete contact records. Sync contact data from your CRM, database, or any external system.

Manage Lists

Add contacts to lists and remove them programmatically - useful for segmenting audiences before sending broadcasts.

Trigger Automations

Kick-off any Unecast automation for a specific contact via a single API call, letting your external systems control when automations run.

Retrieve Conversation History

Pull message history for any contact or conversation - useful for building dashboards, audit logs, or syncing chat data to a data warehouse.

Webhooks

Register webhook endpoints to receive real-time notifications when new messages arrive, contacts are updated, or automations complete.

Sending a WhatsApp Template Message

The example below sends a pre-approved WhatsApp template named hello_world

curl -X POST "https://flow.unecast.com/api/v1/messages/template" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "919876543210",
  "templateName": "hello_world",
  "language": "en_US",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "John Doe"
        },
        {
          "type": "text",
          "text": "ORD-12345"
        }
      ]
    }
  ]
}'

A successful response returns a 200 statuswith the message object:

{
  "success": true,
  "data": {
    "messageId": "uuid-xxx",
    "whatsappMessageId": "wamid.xxx",
    "contactId": "uuid-xxx",
    "conversationId": "uuid-xxx",
    "status": "sent"
  }
}

Reply to a message

Send a free-text reply within the 24-hour customer service window

This endpoint only works when the contact has sent you a message in the last 24 hours (WhatsApp’s customer service window). If the window has expired, use the template message endpoint instead. Phone number format: digits only with country code (e.g. 919876543210).

curl -X POST "https://flow.unecast.com/api/v1/messages/reply" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "919876543210",
  "message": "Hello! Your order has been shipped."
}'

A successful response returns a 200 statuswith the message object:

{
  "success": true,
  "data": {
    "messageId": "uuid-xxx",
    "whatsappMessageId": "wamid.xxx",
    "status": "sent"
  }
}

Track Delivery Status

Get delivery status of a specific message

Replace :messageId with the messageId returned when the message was sent.

curl -X GET "https://flow.unecast.com/api/v1/messages/status/:messageId" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID"

A successful response returns a 200 statuswith the message object:

{
  "success": true,
  "data": {
    "id": "uuid-xxx",
    "whatsappMessageId": "wamid.xxx",
    "status": "delivered",
    "deliveredAt": "2024-01-01T12:00:00Z",
    "readAt": null,
    "errorCode": null,
    "errorMessage": null,
    "createdAt": "2024-01-01T11:59:00Z"
  }
}

Contacts

List all contacts with optional filters

Query Parameters = ?search=John&limit=50&offset=0&groupId=xxx

curl -X GET "https://flow.unecast.com/api/v1/contacts?search=John&limit=50&offset=0&groupId=xxx" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID"

A successful response returns a 200 statuswith the message object:

{
  "success": true,
  "data": {
    "contacts": [],
    "total": 0
  }
}

Create a new contact

Phone number must include country code, digits only (e.g. 919876543210). Returns 409 if the contact already exists.

curl -X POST "https://flow.unecast.com/api/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "919876543210",
  "name": "John Doe",
  "email": "john@example.com"
}'

A successful response returns a 200 statuswith the message object:

{
  "success": true,
  "data": {
    "id": "uuid-xxx",
    "phone": "919876543210",
    "name": "John Doe"
  }
}

Update an existing contact

curl -X PUT "https://flow.unecast.com/api/v1/contacts/:id" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "John Updated",
  "email": "john.new@example.com"
}'

A successful response returns a 200 statuswith the message object:

{
  "success": true,
  "data": {
    "id": "uuid-xxx",
    "name": "John Updated"
  }
}

Delete a contact permanently

curl -X DELETE "https://flow.unecast.com/api/v1/contacts/:id" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID"

A successful response returns a 200 statuswith the message object:

{
  "success": true,
  "data": {
    "message": "Contact deleted successfully"
  }
}

List all contact groups

curl -X GET "https://flow.unecast.com/api/v1/contacts/groups" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID"

A successful response returns a 200 statuswith the message object:

{
  "success": true,
  "data": []
}

Add a contact to a group

curl -X POST "https://flow.unecast.com/api/v1/contacts/groups/:groupId/add" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "contactId": "uuid-xxx"
}'

A successful response returns a 200 statuswith the message object:

{
  "success": true,
  "data": {
    "message": "Contact added to group"
  }
}

Templates

List all templates belonging to a channel

Query Parameters = ?status=APPROVED

curl -X GET "https://flow.unecast.com/api/v1/templates?status=APPROVED" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID"

A successful response returns a 200 statuswith the message object:

{
  "success": true,
  "data": [
    {
      "id": "uuid-xxx",
      "name": "hello_world",
      "status": "APPROVED",
      "language": "en_US",
      "category": "MARKETING"
    }
  ]
}

Campaigns

List all campaigns with optional filters

Query Parameters = ?status=completed&limit=10&offset=0

curl -X GET "https://flow.unecast.com/api/v1/campaigns?status=completed&limit=10&offset=0" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID"

A successful response returns a 200 statuswith the message object:

esponse

{
  "success": true,
  "data": {
    "campaigns": [],
    "total": 0,
    "limit": 10,
    "offset": 0
  }
}

Account

Get channel information and API details

curl -X GET "https://flow.unecast.com/api/v1/account" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID"

A successful response returns a 200 statuswith the message object:

{
  "success": true,
  "data": {
    "campaigns": [],
    "total": 0,
    "limit": 10,
    "offset": 0
  }
}

{
  "success": true,
  "data": {
    "userId": "uuid-xxx",
    "channel": {
      "id": "uuid-xxx",
      "name": "My Channel",
      "phoneNumber": "+919876543210",
      "isActive": true,
      "healthStatus": "healthy"
    },
    "usage": {
      "requestCount": 1250,
      "monthlyRequestCount": 340,
      "monthlyResetAt": "2024-02-01T00:00:00Z",
      "lastUsedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Get detailed API usage and breakdown by time period

curl -X GET "https://flow.unecast.com/api/v1/account/usage" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Channel-Id: YOUR_CHANNEL_ID"

A successful response returns a 200 statuswith the message object:

{
  "success": true,
  "data": {
    "last24Hours": 42,
    "last7Days": 310,
    "total": 1250,
    "recentRequests": [
      {
        "endpoint": "/api/v1/messages/template",
        "method": "POST",
        "statusCode": 200,
        "responseTime": 312,
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ]
  }
}

Error Codes

400 - Bad Request. The request body or parameters are invalid 401 - Unauthorized. Invalid or missing API key/secret 403 - Forbidden. Insufficient permissions for this action or 24-hour window expired 404 - Not Found. The requested resource does not exist 409 - Conflict. Resource already exists (e.g. duplicate contact phone) 429 - Rate Limited. Too many requests - slow down or upgrade your plan 500 - Internal Server Error. Something went wrong on our end.

Getting Your API Key

Open Unecast Platform

In Unecast, navigate to Settings→ API.

Generate a Key

Click Generate API Key. Give the key a descriptive name (e.g., “Production Integration”) so you can identify it later.

Playground

Once an API key is created, you’ll get access to a playground where you can try the API by calling any available endpoint directly from the Unecast dashboard.

Get Started

Core Features

Integrations

Channels & Setup

Security & Compliance

Unecast API: Build Custom Integrations and Workflows

Authentication

Core Capabilities

Send Messages

Manage Contacts

Manage Lists

Trigger Automations

Retrieve Conversation History

Webhooks

Sending a WhatsApp Template Message

Reply to a message

Track Delivery Status

Contacts

List all contacts with optional filters

Create a new contact

Update an existing contact

Delete a contact permanently

List all contact groups

Add a contact to a group

Templates

List all templates belonging to a channel

Campaigns

List all campaigns with optional filters

Account

Get channel information and API details

Get detailed API usage and breakdown by time period

Error Codes

Getting Your API Key

​Authentication

​Core Capabilities

Send Messages

Manage Contacts

Manage Lists

Trigger Automations

Retrieve Conversation History

Webhooks

​Sending a WhatsApp Template Message

​Reply to a message

​Track Delivery Status

​Contacts

​List all contacts with optional filters

​Create a new contact

​Update an existing contact

​Delete a contact permanently

​List all contact groups

​Add a contact to a group

​Templates

​List all templates belonging to a channel

​Campaigns

​List all campaigns with optional filters

​Account

​Get channel information and API details

​Get detailed API usage and breakdown by time period

​Error Codes

​Getting Your API Key

Authentication

Core Capabilities

Sending a WhatsApp Template Message

Reply to a message

Track Delivery Status

Contacts

List all contacts with optional filters

Create a new contact

Update an existing contact

Delete a contact permanently

List all contact groups

Add a contact to a group

Templates

List all templates belonging to a channel

Campaigns

List all campaigns with optional filters

Account

Get channel information and API details

Get detailed API usage and breakdown by time period

Error Codes

Getting Your API Key