WhatsApp

Access connected WhatsApp Business accounts, send messages, and manage chat threads.

WhatsApp APIs are only available after connecting a WhatsApp Business Account (WABA) in Settings → Integrations → WhatsApp.

Get Connected Accounts

List all WhatsApp Business accounts connected to your organization.

GET /api/v1/whatsapp/accounts

Required scope: whatsapp:read

Example Request

curl -X GET "https://app.erzycall.com/api/v1/whatsapp/accounts" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": [
    {
      "id": "wa_acct_abc123",
      "status": "active",
      "statusMessage": null,
      "wabaId": "123456789012345",
      "phoneNumberId": "987654321098765",
      "displayPhoneNumber": "+60360431879",
      "verifiedName": "My Business",
      "qualityRating": "GREEN",
      "messagesSent": 142,
      "messagesReceived": 89,
      "lastMessageAt": "2025-01-15T14:30:00.000Z",
      "createdAt": "2025-01-01T09:00:00.000Z"
    }
  ]
}

Account Status Values

Status	Description
`active`	Connected and ready to send/receive messages
`disconnected`	Disconnected — no messages can be sent
`error`	Connection error — check `statusMessage` for details
`pending_setup`	Setup in progress

List Conversations

Retrieve chat threads for your organization, sorted by most recent activity.

GET /api/v1/whatsapp/conversations

Required scope: whatsapp:read

Query Parameters

Parameter	Type	Default	Description
`limit`	`integer`	`25`	Results per page (1–100)
`cursor`	`string`	—	Pagination cursor from a previous response
`status`	`string`	—	Filter by status: `active`, `handed_off`, `closed`

Example Request

curl -X GET "https://app.erzycall.com/api/v1/whatsapp/conversations?limit=10&status=active" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": [
    {
      "id": "conv_abc123",
      "status": "active",
      "waUserPhone": "+60111234567",
      "waUserName": "Ahmad Razif",
      "contactId": "contact_456",
      "integrationId": "wa_acct_abc123",
      "lastMessagePreview": "Sure, I'll look into it right away.",
      "lastMessageDirection": "outbound",
      "lastUserMessageAt": "2025-01-15T14:25:00.000Z",
      "sessionExpiresAt": "2025-01-16T14:25:00.000Z",
      "messageCount": 12,
      "aiSummary": null,
      "createdAt": "2025-01-14T10:00:00.000Z",
      "updatedAt": "2025-01-15T14:25:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "eyJwb3...",
    "hasMore": true,
    "pageSize": 10
  }
}

Conversation Status Values

Status	Description
`active`	Ongoing — bot or agent is handling the thread
`handed_off`	Escalated to a human agent
`closed`	Resolved and closed

Get Conversation

Retrieve a single conversation including its recent message history.

GET /api/v1/whatsapp/conversations/{id}

Required scope: whatsapp:read

Example Request

curl -X GET "https://app.erzycall.com/api/v1/whatsapp/conversations/conv_abc123" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": {
    "id": "conv_abc123",
    "status": "active",
    "waUserPhone": "+60111234567",
    "waUserName": "Ahmad Razif",
    "contactId": "contact_456",
    "integrationId": "wa_acct_abc123",
    "lastMessagePreview": "Sure, I'll look into it right away.",
    "lastMessageDirection": "outbound",
    "lastUserMessageAt": "2025-01-15T14:25:00.000Z",
    "sessionExpiresAt": "2025-01-16T14:25:00.000Z",
    "messageCount": 12,
    "aiSummary": null,
    "createdAt": "2025-01-14T10:00:00.000Z",
    "updatedAt": "2025-01-15T14:25:00.000Z",
    "messages": [
      {
        "id": "msg_001",
        "direction": "inbound",
        "senderType": "user",
        "messageType": "text",
        "text": "Hi, I'd like to know more about your plans.",
        "mediaUrl": null,
        "mediaCaption": null,
        "deliveryStatus": null,
        "timestamp": "2025-01-15T14:20:00.000Z",
        "createdAt": "2025-01-15T14:20:00.000Z"
      },
      {
        "id": "msg_002",
        "direction": "outbound",
        "senderType": "bot",
        "messageType": "text",
        "text": "Sure, I'll look into it right away.",
        "mediaUrl": null,
        "mediaCaption": null,
        "deliveryStatus": "read",
        "timestamp": "2025-01-15T14:25:00.000Z",
        "createdAt": "2025-01-15T14:25:00.000Z"
      }
    ]
  }
}

Returns up to the 50 most recent messages, in chronological order.

Errors

Status	Code	Description
404	`NOT_FOUND`	Conversation not found

24-hour session window: WhatsApp only allows free-form text messages within 24 hours of the last inbound message. Once the window expires, you must send a template message to re-open the conversation. Check sessionExpiresAt on the conversation to see when the window closes.

Send Text Message

Send a plain text message within an active session window.

Request Body

Field	Type	Required	Description
`type`	`string`	Yes	Must be `"text"`
`conversationId`	`string`	Yes	ID of the conversation to send to
`text`	`string`	Yes	Message text (max 4,096 characters)

Example Request

curl -X POST "https://app.erzycall.com/api/v1/whatsapp/messages" \
  -H "X-API-Key: ek_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "conversationId": "conv_abc123",
    "text": "Hi Ahmad, your appointment is confirmed for tomorrow at 10am."
  }'

Example Response (201 Created)

{
  "data": {
    "messageId": "wamid.HBgLNjAxMTIzNDU2N...",
    "type": "text"
  }
}

Errors

Status	Code	Description
404	`NOT_FOUND`	Conversation not found or no active integration
422	`SESSION_EXPIRED`	24-hour window expired — send a template instead
502	`WHATSAPP_API_ERROR`	Meta API rejected the message

Send Template Message

Send a pre-approved WhatsApp message template. Templates can be sent at any time — they are the only way to initiate or re-open a conversation after the 24-hour window closes.

Templates must be APPROVED in your WhatsApp Business Manager before they can be sent. You can sync and view your templates in Settings → Integrations → WhatsApp → Templates.

Request Body

Field	Type	Required	Description
`type`	`string`	Yes	Must be `"template"`
`conversationId`	`string`	Yes	ID of the conversation to send to
`templateName`	`string`	Yes	Exact template name as registered in Meta Business Manager
`templateLanguage`	`string`	Yes	Language code (e.g., `en_US`, `ms`, `ar`)
`variables`	`object`	No	Key-value pairs to fill template placeholders (e.g., `{"name": "Ahmad", "date": "Jan 16"}`)

Example Request

curl -X POST "https://app.erzycall.com/api/v1/whatsapp/messages" \
  -H "X-API-Key: ek_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "template",
    "conversationId": "conv_abc123",
    "templateName": "appointment_reminder",
    "templateLanguage": "en_US",
    "variables": {
      "name": "Ahmad",
      "date": "January 16",
      "time": "10:00 AM"
    }
  }'

Example Response (201 Created)

{
  "data": {
    "messageId": "wamid.HBgLNjAxMTIzNDU2N...",
    "type": "template",
    "template": {
      "name": "appointment_reminder",
      "language": "en_US"
    }
  }
}

Errors

Status	Code	Description
404	`NOT_FOUND`	Conversation not found or no active integration
404	`TEMPLATE_NOT_FOUND`	Template not found or status is not `APPROVED`
502	`WHATSAPP_API_ERROR`	Meta API rejected the message (e.g., template parameter mismatch)

Template variables: Variable names must match the parameter names defined in your template. For templates using positional parameters ({{1}}, {{2}}), use "1", "2" as the keys in the variables object.

WhatsApp APIs are only available after connecting a WhatsApp Business Account (WABA) in Settings → Integrations → WhatsApp.

Get Connected Accounts

List all WhatsApp Business accounts connected to your organization.

GET /api/v1/whatsapp/accounts

Required scope: whatsapp:read

Example Request

curl -X GET "https://app.erzycall.com/api/v1/whatsapp/accounts" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": [
    {
      "id": "wa_acct_abc123",
      "status": "active",
      "statusMessage": null,
      "wabaId": "123456789012345",
      "phoneNumberId": "987654321098765",
      "displayPhoneNumber": "+60360431879",
      "verifiedName": "My Business",
      "qualityRating": "GREEN",
      "messagesSent": 142,
      "messagesReceived": 89,
      "lastMessageAt": "2025-01-15T14:30:00.000Z",
      "createdAt": "2025-01-01T09:00:00.000Z"
    }
  ]
}

Account Status Values

Status	Description
`active`	Connected and ready to send/receive messages
`disconnected`	Disconnected — no messages can be sent
`error`	Connection error — check `statusMessage` for details
`pending_setup`	Setup in progress

List Conversations

Retrieve chat threads for your organization, sorted by most recent activity.

GET /api/v1/whatsapp/conversations

Required scope: whatsapp:read

Query Parameters

Parameter	Type	Default	Description
`limit`	`integer`	`25`	Results per page (1–100)
`cursor`	`string`	—	Pagination cursor from a previous response
`status`	`string`	—	Filter by status: `active`, `handed_off`, `closed`

Example Request

curl -X GET "https://app.erzycall.com/api/v1/whatsapp/conversations?limit=10&status=active" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": [
    {
      "id": "conv_abc123",
      "status": "active",
      "waUserPhone": "+60111234567",
      "waUserName": "Ahmad Razif",
      "contactId": "contact_456",
      "integrationId": "wa_acct_abc123",
      "lastMessagePreview": "Sure, I'll look into it right away.",
      "lastMessageDirection": "outbound",
      "lastUserMessageAt": "2025-01-15T14:25:00.000Z",
      "sessionExpiresAt": "2025-01-16T14:25:00.000Z",
      "messageCount": 12,
      "aiSummary": null,
      "createdAt": "2025-01-14T10:00:00.000Z",
      "updatedAt": "2025-01-15T14:25:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "eyJwb3...",
    "hasMore": true,
    "pageSize": 10
  }
}

Conversation Status Values

Status	Description
`active`	Ongoing — bot or agent is handling the thread
`handed_off`	Escalated to a human agent
`closed`	Resolved and closed

Get Conversation

Retrieve a single conversation including its recent message history.

GET /api/v1/whatsapp/conversations/{id}

Required scope: whatsapp:read

Example Request

curl -X GET "https://app.erzycall.com/api/v1/whatsapp/conversations/conv_abc123" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": {
    "id": "conv_abc123",
    "status": "active",
    "waUserPhone": "+60111234567",
    "waUserName": "Ahmad Razif",
    "contactId": "contact_456",
    "integrationId": "wa_acct_abc123",
    "lastMessagePreview": "Sure, I'll look into it right away.",
    "lastMessageDirection": "outbound",
    "lastUserMessageAt": "2025-01-15T14:25:00.000Z",
    "sessionExpiresAt": "2025-01-16T14:25:00.000Z",
    "messageCount": 12,
    "aiSummary": null,
    "createdAt": "2025-01-14T10:00:00.000Z",
    "updatedAt": "2025-01-15T14:25:00.000Z",
    "messages": [
      {
        "id": "msg_001",
        "direction": "inbound",
        "senderType": "user",
        "messageType": "text",
        "text": "Hi, I'd like to know more about your plans.",
        "mediaUrl": null,
        "mediaCaption": null,
        "deliveryStatus": null,
        "timestamp": "2025-01-15T14:20:00.000Z",
        "createdAt": "2025-01-15T14:20:00.000Z"
      },
      {
        "id": "msg_002",
        "direction": "outbound",
        "senderType": "bot",
        "messageType": "text",
        "text": "Sure, I'll look into it right away.",
        "mediaUrl": null,
        "mediaCaption": null,
        "deliveryStatus": "read",
        "timestamp": "2025-01-15T14:25:00.000Z",
        "createdAt": "2025-01-15T14:25:00.000Z"
      }
    ]
  }
}

Returns up to the 50 most recent messages, in chronological order.

Errors

Status	Code	Description
404	`NOT_FOUND`	Conversation not found

Send Message

Send a text message or approved template to an existing conversation.

POST /api/v1/whatsapp/messages

Required scope: whatsapp:write

Send Text Message

Send a plain text message within an active session window.

Request Body

Field	Type	Required	Description
`type`	`string`	Yes	Must be `"text"`
`conversationId`	`string`	Yes	ID of the conversation to send to
`text`	`string`	Yes	Message text (max 4,096 characters)

Example Request

curl -X POST "https://app.erzycall.com/api/v1/whatsapp/messages" \
  -H "X-API-Key: ek_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "conversationId": "conv_abc123",
    "text": "Hi Ahmad, your appointment is confirmed for tomorrow at 10am."
  }'

Example Response (201 Created)

{
  "data": {
    "messageId": "wamid.HBgLNjAxMTIzNDU2N...",
    "type": "text"
  }
}

Errors

Status	Code	Description
404	`NOT_FOUND`	Conversation not found or no active integration
422	`SESSION_EXPIRED`	24-hour window expired — send a template instead
502	`WHATSAPP_API_ERROR`	Meta API rejected the message

Send Template Message

Send a pre-approved WhatsApp message template. Templates can be sent at any time — they are the only way to initiate or re-open a conversation after the 24-hour window closes.

Templates must be APPROVED in your WhatsApp Business Manager before they can be sent. You can sync and view your templates in Settings → Integrations → WhatsApp → Templates.

Request Body

Field	Type	Required	Description
`type`	`string`	Yes	Must be `"template"`
`conversationId`	`string`	Yes	ID of the conversation to send to
`templateName`	`string`	Yes	Exact template name as registered in Meta Business Manager
`templateLanguage`	`string`	Yes	Language code (e.g., `en_US`, `ms`, `ar`)
`variables`	`object`	No	Key-value pairs to fill template placeholders (e.g., `{"name": "Ahmad", "date": "Jan 16"}`)

Example Request

curl -X POST "https://app.erzycall.com/api/v1/whatsapp/messages" \
  -H "X-API-Key: ek_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "template",
    "conversationId": "conv_abc123",
    "templateName": "appointment_reminder",
    "templateLanguage": "en_US",
    "variables": {
      "name": "Ahmad",
      "date": "January 16",
      "time": "10:00 AM"
    }
  }'

Example Response (201 Created)

{
  "data": {
    "messageId": "wamid.HBgLNjAxMTIzNDU2N...",
    "type": "template",
    "template": {
      "name": "appointment_reminder",
      "language": "en_US"
    }
  }
}

Errors

Status	Code	Description
404	`NOT_FOUND`	Conversation not found or no active integration
404	`TEMPLATE_NOT_FOUND`	Template not found or status is not `APPROVED`
502	`WHATSAPP_API_ERROR`	Meta API rejected the message (e.g., template parameter mismatch)

On this page

WhatsApp

On this page