> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unecast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Unecast API: Build Custom Integrations and Workflows

> Use the Unecast REST API to send messages, manage contacts, trigger automations, and receive real-time events via webhooks in your own systems.

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.

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Send Messages" icon="paper-plane">
    Send WhatsApp messages, SMS, and other channel messages to any contact. Use pre-approved WhatsApp templates for business-initiated outreach.
  </Card>

  <Card title="Manage Contacts" icon="address-book">
    Create, read, update, and delete contact records. Sync contact data from your CRM, database, or any external system.
  </Card>

  <Card title="Manage Lists" icon="list-check">
    Add contacts to lists and remove them programmatically - useful for segmenting audiences before sending broadcasts.
  </Card>

  <Card title="Trigger Automations" icon="bolt">
    Kick-off any Unecast automation for a specific contact via a single API call, letting your external systems control when automations run.
  </Card>

  <Card title="Retrieve Conversation History" icon="clock-rotate-left">
    Pull message history for any contact or conversation - useful for building dashboards, audit logs, or syncing chat data to a data warehouse.
  </Card>

  <Card title="Webhooks" icon="webhook">
    Register webhook endpoints to receive real-time notifications when new messages arrive, contacts are updated, or automations complete.
  </Card>
</CardGroup>

## Sending a WhatsApp Template Message

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

```bash theme={null}
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 status`with the message object:

```json theme={null}
{
  "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

<Note>
  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).
</Note>

```bash theme={null}
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 status`with the message object:

```json theme={null}
{
  "success": true,
  "data": {
    "messageId": "uuid-xxx",
    "whatsappMessageId": "wamid.xxx",
    "status": "sent"
  }
}
```

## Track Delivery Status

Get delivery status of a specific message

<Note>
  Replace :messageId with the messageId returned when the message was sent.
</Note>

```bash theme={null}
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 status`with the message object:

```json theme={null}
{
  "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

<Note>
  Query Parameters = ?search=John\&limit=50\&offset=0\&groupId=xxx
</Note>

```bash theme={null}
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 status`with the message object:

```json theme={null}
{
  "success": true,
  "data": {
    "contacts": [],
    "total": 0
  }
}
```

## Create a new contact

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

```bash theme={null}
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 status`with the message object:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "uuid-xxx",
    "phone": "919876543210",
    "name": "John Doe"
  }
}
```

## Update an existing contact

```bash theme={null}
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 status`with the message object:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "uuid-xxx",
    "name": "John Updated"
  }
}
```

## Delete a contact permanently

```bash theme={null}
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 status`with the message object:

```json theme={null}
{
  "success": true,
  "data": {
    "message": "Contact deleted successfully"
  }
}
```

## List all contact groups

```bash theme={null}
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 status`with the message object:

```json theme={null}
{
  "success": true,
  "data": []
}
```

## Add a contact to a group

```bash theme={null}
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 status`with the message object:

```json theme={null}
{
  "success": true,
  "data": {
    "message": "Contact added to group"
  }
}
```

# Templates

## List all templates belonging to a channel

<Note>
  Query Parameters = `?status=APPROVED`
</Note>

```bash theme={null}
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 status`with the message object:

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

# Campaigns

## List all campaigns with optional filters

<Note>
  Query Parameters = `?status=completed&limit=10&offset=0`
</Note>

```bash highlight={1} theme={null}
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 status`with the message object:

```json theme={null}
esponse

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

# Account

## Get channel information and API details

```bash highlight={1} theme={null}
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 status`with the message object:

```json theme={null}
{
  "success": true,
  "data": {
    "campaigns": [],
    "total": 0,
    "limit": 10,
    "offset": 0
  }
}
```

```json theme={null}
{
  "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

```bash highlight={1} theme={null}
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 status`with the message object:

```json theme={null}
{
  "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

<Steps>
  <Step title="Open Unecast Platform">
    In Unecast, navigate to **Settings→ API**.
  </Step>

  <Step title="Generate a Key">
    Click **Generate API Key**. Give the key a descriptive name (e.g., "Production Integration") so you can identify it later.
  </Step>

  <Step title="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.
  </Step>
</Steps>