Developer DocumentationExplore guides, APIs and resources to build with Sprout

Build with Sprout

Sprout provides two REST APIs. Use the WhatsApp API Gateway to send messages out, and the Business API to read contacts and conversation history back. Choose the one that matches what you need to do.

WhatsApp API Gateway

REST · Bearer token · Read and write

Manage WhatsApp message templates, send approved template messages to recipients, and receive delivery, read and inbound-message webhook events.

Message template management
Send template messages
Message status webhooks
Incoming customer messages

Business API v1

REST · API key · Read-only

Pull your enterprise's contacts and leads, and the full conversation history for any contact, into your CRM, data warehouse or reporting tools.

List contacts and leads
Retrieve conversation history
Rich media, templates and call events
Self-service API keys

Which API do I need?

What you want to do	Use this API
Send a WhatsApp message to a customer	WhatsApp API Gateway
Create, edit or delete a message template	WhatsApp API Gateway
Be notified the moment a message is delivered or read	WhatsApp API Gateway (webhooks)
React to an incoming customer message in real time	WhatsApp API Gateway (webhooks)
Export your leads into a CRM	Business API v1
Read the full chat transcript for a contact	Business API v1
Back-fill past conversations for reporting	Business API v1

The two APIs are separate products with separate base URLs and separate credentials. Neither one replaces the other.

Getting Started

Choose your API Use the table above, or the switcher at the top of the sidebar.
Get your credentials Request a bearer token for the Gateway, or create an API key for the Business API from the Sprout admin UI.
Make your first call Copy a cURL example from any endpoint page and replace the placeholder values with your own.

API GatewayConnect, automate and scale WhatsApp experiences

Sprout WhatsApp API Gateway

Integrate WhatsApp messaging capabilities into external systems using a simplified REST API.

The Sprout WhatsApp API Gateway allows developers to manage WhatsApp message templates, send approved template messages, receive message-status updates and process incoming customer messages.

Main Capabilities

Message Template Management

Retrieve, create, edit and delete WhatsApp message templates.

Send Template Messages

Send approved WhatsApp message templates to recipients.

Message Status Updates

Receive asynchronous updates when messages are sent, delivered or read.

Incoming Customer Messages

Receive customer replies and message details through webhook events.

Getting Started

Configure the Base URL Use the Sprout WhatsApp API Gateway base URL.
Add Authentication Include the bearer token in the authorization header.
Identify the Required IDs Use the WABA ID, phone number ID and template ID in the relevant endpoints.
Manage Templates Retrieve, create, edit or delete WhatsApp templates.
Send a Template Message Send an approved template using the phone number ID.
Receive Webhook Events Receive status updates and incoming customer messages.

Looking for contact and conversation data?

To read your contacts or pull chat transcripts into another system, use the Business API instead.

Secure AccessAuthenticate every request with a bearer token

Authentication

All API endpoints require bearer token authentication.

Required Headers

Authorization

Authorization: Bearer <AUTH_TOKEN>

Content Type

Content-Type: application/json

Example request headers

curl 'https://app.hellosprout.ai/whatsapp-gw/api/<ENDPOINT>' \
  -H 'Authorization: Bearer <AUTH_TOKEN>' \
  -H 'Content-Type: application/json'

Template LibraryRetrieve all templates connected to a WABA

List Templates

Retrieve the message templates available under a WhatsApp Business Account.

GET /<WABA_ID>/message_templates

Required Information

WhatsApp Business Account ID
Authorization bearer token

Response Information

The response may include:

Template name

Parameter format

Template components

Header details

Body text

Example parameter values

Buttons

Language

Status

Category

Template ID

Pagination cursors

Common Values

Languageen_US

StatusAPPROVED

CategoryMARKETING

Paging

Pagination information may include:

Before cursor
After cursor

Example Request

cURL

curl 'https://app.hellosprout.ai/whatsapp-gw/api/<WABA_ID>/message_templates' \
  -H 'Authorization: Bearer <AUTH_TOKEN>'

Example Response

JSON

{
  "data": [
    {
      "name": "text_params_button",
      "parameter_format": "NAMED",
      "components": [
        {
          "type": "HEADER",
          "format": "TEXT",
          "text": "sample_text"
        },
        {
          "type": "BODY",
          "text": "O {{name}}, chosen of fortune, Emrys and Morgana do summon thee...",
          "example": {
            "body_text_named_params": [
              {
                "param_name": "name",
                "example": "Arthur"
              },
              {
                "param_name": "bell_location",
                "example": "Avalon Tower"
              }
            ]
          }
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "QUICK_REPLY",
              "text": "Turn Away"
            },
            {
              "type": "PHONE_NUMBER",
              "text": "Heed the Summons",
              "phone_number": "+94716925097"
            }
          ]
        }
      ],
      "language": "en_US",
      "status": "APPROVED",
      "category": "MARKETING",
      "id": "1308035194697923"
    }
  ],
  "paging": {
    "cursors": {
      "before": "cursor-string",
      "after": "cursor-string"
    }
  }
}

Template CreationBuild structured WhatsApp templates

Create Template

Create a new WhatsApp message template under a WhatsApp Business Account.

POST /<WABA_ID>/message_templates

Request Body Fields

Field	Type	Required	Description
`name`	string	Yes	Template name
`category`	string	Yes	UTILITY or MARKETING
`language`	string	Yes	Language code, for example `en_US`
`parameter_format`	string	Yes	`NAMED`
`components`	array	Yes	Template content

Supported Template Components

Header

Type
Format
Text

Body

Message text
Named parameters
Example parameter values

Footer

Includes footer text

Buttons

Quick reply button

Response

The response includes:

Template ID
Status
Category

A newly created template may return the status PENDING.

Example Request

JSON

{
  "name": "sample_text_template",
  "category": "UTILITY",
  "language": "en_US",
  "parameter_format": "NAMED",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Sample Header"
    },
    {
      "type": "BODY",
      "text": "Hello {{name}}, your order is ready.",
      "example": {
        "body_text_named_params": [
          {
            "param_name": "name",
            "example": "John"
          }
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Thank you"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Quick Reply Button"
        }
      ]
    }
  ]
}

Example Response

JSON

{
  "id": "987654321",
  "status": "PENDING",
  "category": "UTILITY"
}

Template EditingUpdate existing WhatsApp templates safely

Edit Template

Edit an existing WhatsApp message template.

POST /<TEMPLATE_ID>

Eligible Template Statuses

APPROVED REJECTED PAUSED

Editable Properties

Category
Components
Time-to-live

Important Editing Rules

Individual template components cannot be edited separately.
All components are replaced by the components included in the edit request.
The category of an approved template cannot be edited.
Approved templates can be edited up to 10 times within a 30-day period.
Approved templates can be edited once within a 24-hour period.
Rejected or paused templates can be edited an unlimited number of times.
After editing an approved or paused template, it will automatically be approved unless it fails template review.

Response

Success status
Template ID
Template name
Template category

Example Request

JSON

{
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "A Proclamation of Hidden Sorcery"
    },
    {
      "type": "BODY",
      "text": "Sample Edited Text."
    }
  ]
}

Example Response

JSON

{
  "success": true,
  "id": "889288737024431",
  "name": "text_only",
  "category": "MARKETING"
}

Template RemovalDelete WhatsApp templates using their ID and name

Delete Template

Delete a WhatsApp message template using its ID and name.

DELETE /<WABA_ID>/message_templates?hsm_id=<TEMPLATE_ID>&name=<TEMPLATE_NAME>

Required Query Information

hsm_id

Message Template ID

The unique ID of the message template.

name

Template Name

The name assigned to the message template.

Required Information

WhatsApp Business Account ID
Template ID
Template name
Authorization bearer token

Example Request

cURL

curl -X DELETE \
  'https://app.hellosprout.ai/whatsapp-gw/api/<WABA_ID>/message_templates?hsm_id=<TEMPLATE_ID>&name=<TEMPLATE_NAME>' \
  -H 'Authorization: Bearer <AUTH_TOKEN>'

Example Response

JSON

{
  "success": true
}

Message DeliverySend approved templates to recipients

Send Template Message

Send a WhatsApp template message using the connected WhatsApp business phone number.

POST /<PHONE_NUMBER_ID>/messages

Request Body Fields

Field	Type	Required	Description
`messaging_product`	string	Yes	Must be `whatsapp`
`to`	string	Yes	Recipient number in E.164 format
`type`	string	Yes	Must be `template`
`template`	object	Yes	Template configuration

Template Configuration

NameThe approved template name.

Languageen_US

ComponentsContains the dynamic values required by the template.

Named Parameters

The documented body parameter includes:

Type
Parameter name
Text value

Named parameters allow the template to insert customer-specific content.

Response

Messaging product: the messaging platform used.
Contacts: the original recipient input and WhatsApp ID.
Messages: the message ID and message status.

The example message status is accepted. An accepted response means the gateway has taken the message. Actual delivery is confirmed later through webhook events.

Example Payload

JSON

{
  "messaging_product": "whatsapp",
  "to": "+94712345678",
  "type": "template",
  "template": {
    "name": "sample_text_template",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "parameter_name": "name",
            "text": "John"
          },
          {
            "type": "text",
            "parameter_name": "name",
            "text": "sample_text"
          }
        ]
      }
    ]
  }
}

Example Response

JSON

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "+94716935097",
      "wa_id": "94716935097"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLOTQ3MTY5MzUwOTcVAgARGBI4NkVDOTIzRjdCREFDNDRBRDUA",
      "message_status": "accepted"
    }
  ]
}

Reading this message back later

A template you send here appears in the Business API conversation history with the content type TEMPLATE_MESSAGE.

Sent Webhook Event

The sent event is generated when a WhatsApp message reaches the sent status.

Status value sent

Payload Information

Object type: whatsapp_business_account
WhatsApp Business Account entry ID
Messaging product
Display phone number
Phone number ID
Message ID
Status
Timestamp
Recipient phone number
Billable value
Pricing model
Message category
Pricing type
Webhook field: messages

Documented Pricing Values

Pricing modelPMP

Categorymarketing

Typeregular

Example Webhook Payload

Sent webhook payload

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "1435343061523969",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<PHONE_NUMBER_ID>"
            },
            "statuses": [
              {
                "id": "<MESSAGE_ID>",
                "status": "sent",
                "timestamp": "1770893055",
                "recipient_id": "<RECIPIENT_PHONE_NUMBER>",
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "category": "marketing",
                  "type": "regular"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Delivered Webhook Event

The delivered event is generated when a WhatsApp message reaches the delivered status.

Status value delivered

Payload Information

Object type: whatsapp_business_account
WhatsApp Business Account entry ID
Messaging product
Display phone number
Phone number ID
Message ID
Status
Timestamp
Recipient phone number
Billable value
Pricing model
Message category
Pricing type
Webhook field: messages

Documented Pricing Values

Pricing modelPMP

Categorymarketing

Typeregular

Example Webhook Payload

Delivered webhook payload

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "1435343061523969",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<PHONE_NUMBER_ID>"
            },
            "statuses": [
              {
                "id": "<MESSAGE_ID>",
                "status": "delivered",
                "timestamp": "1770893055",
                "recipient_id": "<RECIPIENT_PHONE_NUMBER>",
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "category": "marketing",
                  "type": "regular"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Read Webhook Event

The read event is generated when a WhatsApp message reaches the read status.

Status value read

Payload Information

Object type: whatsapp_business_account
WhatsApp Business Account entry ID
Messaging product
Display phone number
Phone number ID
Message ID
Status
Timestamp
Recipient phone number
Billable value
Pricing model
Message category
Pricing type
Webhook field: messages

Documented Pricing Values

Pricing modelPMP

Categorymarketing

Typeregular

Example Webhook Payload

Read webhook payload

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "1435343061523969",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<PHONE_NUMBER_ID>"
            },
            "statuses": [
              {
                "id": "<MESSAGE_ID>",
                "status": "read",
                "timestamp": "1770892507",
                "recipient_id": "<RECIPIENT_PHONE_NUMBER>",
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "category": "marketing",
                  "type": "regular"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Incoming Customer Messages

This webhook event is delivered when a customer replies to one of your WhatsApp messages.

Payload Information

Object type: whatsapp_business_account
WhatsApp Business Account entry ID
Messaging product
Display phone number
Phone number ID
Contact profile name
Contact WhatsApp ID
Message context
Context sender
Context message ID
Sender phone number
Incoming message ID
Timestamp
Text body
Message type
Webhook field: messages

Documented Example Values

Message typetext

Text bodyHi

Example Webhook Payload

Incoming customer message payload

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "1435343061523969",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<REPLIED_CONTACT_NAME>"
                },
                "wa_id": "<RECIPIENT_PHONE_NUMBER>"
              }
            ],
            "messages": [
              {
                "context": {
                  "from": "<DISPLAY_PHONE_NUMBER>",
                  "id": "<CONTEXT_MESSAGE_ID>"
                },
                "from": "<RECIPIENT_PHONE_NUMBER>",
                "id": "<INCOMING_MESSAGE_ID>",
                "timestamp": "1770892557",
                "text": {
                  "body": "Hi"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Need past conversations instead?

Webhooks push messages to you as they arrive. To read historical conversations on demand, use the Business API.

Endpoint ConfigurationBase URL, transport and response conventions

Base URL and Conventions

All Business API requests are sent to a versioned base path over HTTPS.

Base URL

https://<gateway-host>/business-api/v1

Your gateway host is confirmed together with your API access. Replace <gateway-host> with the value supplied for your account.

Conventions

Item	Value
Transport	HTTPS only
Methods	GET only. Version 1 is read-only.
Authentication header	`X-API-Key: <keyId>.<secret>`, required on every request
Content type	`application/json` in responses
Timestamps	ISO-8601 in UTC, for example `2026-07-20T10:15:00Z`
IDs	Opaque strings. Do not attempt to parse them.
Correlation	Every response carries `X-Correlation-ID`. Include it when reporting an issue.

Pagination

Both endpoints use offset pagination through the page and limit query parameters, and return a pagination object in the response.

Field	Description
`page`	The page that was returned
`limit`	The page size that was applied
`total`	Total number of records available
`totalPages`	Total number of pages available
`hasMore`	Whether a further page exists

Secure AccessAuthenticate every request with your API key

Authentication

Every Business API request must include your enterprise API key in the X-API-Key header.

Required Header

X-API-Key: <keyId>.<secret>

How the Key Is Validated

The gateway validates the key, enforces the key's rate limit and endpoint allowlist, and resolves your enterprise before the request reaches the service.

A missing, malformed, revoked or out-of-scope key is rejected at the edge with a 401 INVALID_API_KEY response.

Example Request

cURL

curl -s 'https://<gateway-host>/business-api/v1/contacts?limit=50&page=1' \
  -H 'X-API-Key: <keyId>.<secret>'

ContactsRetrieve the leads captured by your agents

List Contacts

Returns your enterprise's contacts and leads, newest first by creation time.

GET /business-api/v1/contacts

Query Parameters

Parameter	Type	Default	Constraints and notes
`limit`	integer	50	Clamped to a value between 1 and 100
`page`	integer	1	Must be 1 or greater. Offset pagination using page and limit.
`updatedSince`	ISO-8601	—	Optional. Returns contacts created at or after this instant, for incremental polling.

Example Request

cURL

curl -s 'https://<gateway-host>/business-api/v1/contacts?limit=50&page=1' \
  -H 'X-API-Key: <keyId>.<secret>'

Example Response

200 OK

{
  "data": [
    {
      "id": "665f2b8c9a1e4f0012ab34cd",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+94771234567",
      "source": "WEB",
      "customFields": {
        "company": "Acme",
        "budget": "5000"
      },
      "createdOn": "2026-07-20T10:15:00Z",
      "lastUpdatedOn": "2026-07-21T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1234,
    "totalPages": 25,
    "hasMore": true
  }
}

Contact Object

Field	Type	Nullable	Description
`id`	string	No	Stable contact ID. Use this as the `contactId` for the messages endpoint.
`name`	string	Yes	Contact name, if collected.
`email`	string	Yes	Email address, if collected.
`phone`	string	Yes	Phone number in E.164 form, if collected.
`source`	string	No	Acquisition channel: `WEB`, `WHATSAPP`, `FB` or `IG`. Version 1 returns the channel only, not the specific web page URL.
`customFields`	object	No	Key and value map of extra fields the agent collected during the conversation. May be an empty object. Values are strings.
`createdOn`	string	No	When the contact was first recorded, in ISO-8601 UTC. This is the sort key.
`lastUpdatedOn`	string	Yes	The last time the contact record changed.

Notes

Results are sorted by createdOn in descending order.
customFields is derived from the contact's collected data. Malformed data yields an empty object rather than failing the whole row.
To poll incrementally, store the highest createdOn you have seen and pass it as updatedSince on the next call.

Incremental polling is the recommended pattern. It keeps you well inside the rate limit and avoids re-fetching unchanged data.

MessagesRetrieve the full conversation history for a contact

Get Conversation History

Returns the conversation history for one contact, grouped by session.

Sessions are returned in the same order as the admin Conversations screen: the newest session first, with messages inside each session running oldest to newest.

GET /business-api/v1/messages

Query Parameters

Parameter	Type	Default	Constraints and notes
`contactId`	string	—	Required. An ID returned by the contacts endpoint.
`limit`	integer	50	Clamped to a value between 1 and 100. Paginates over session groups, not individual messages.
`page`	integer	1	Must be 1 or greater.

Pagination works on sessions

A limit of 50 returns up to 50 conversation sessions, each of which may contain many messages. It does not return 50 messages.

Example Request

cURL

curl -s 'https://<gateway-host>/business-api/v1/messages?contactId=665f2b8c9a1e4f0012ab34cd&limit=50' \
  -H 'X-API-Key: <keyId>.<secret>'

Example Response

200 OK

{
  "contactId": "665f2b8c9a1e4f0012ab34cd",
  "data": [
    {
      "sessionId": "sess_abc",
      "personaName": "Sales Bot",
      "messages": [
        {
          "messageId": "6690aa11bb22cc33dd44ee55",
          "sender": "visitor",
          "content": "Hi",
          "contentType": "TEXT",
          "createdOn": "2026-07-20T10:15:00Z"
        },
        {
          "messageId": "6690aa11bb22cc33dd44ee56",
          "sender": "bot",
          "content": "Hello! How can I help?",
          "contentType": "TEXT",
          "createdOn": "2026-07-20T10:15:03Z"
        },
        {
          "messageId": "6690aa11bb22cc33dd44ee57",
          "sender": "agent",
          "content": "This is Sam, taking over.",
          "contentType": "TEXT",
          "createdOn": "2026-07-20T10:16:00Z"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 3,
    "totalPages": 1,
    "hasMore": false
  }
}

The structure of each object in the response is described on the page.

Response StructureEvery object returned by the messages endpoint

Response Objects

The messages endpoint returns session blocks, each containing messages, which may in turn carry reactions or call details.

Session Block Object

Field	Type	Nullable	Description
`sessionId`	string	No	Conversation or session identifier.
`personaName`	string	Yes	Name of the agent persona for the session, if known.
`messages`	array	No	Messages in the session, ascending by `createdOn`.

Message Object

Field	Type	Nullable	Description
`messageId`	string	No	Message identifier.
`sender`	string	No	`visitor`, `bot`, `agent` or `system`.
`content`	string	No	Message text. For non-text content types the payload is carried as-is.
`contentType`	string	No	`TEXT`, `JSON`, `REACT`, `TEMPLATE_MESSAGE` or `CALL`.
`createdOn`	string	No	Message timestamp in ISO-8601 UTC.
`reactions`	array	Yes	Emoji reactions applied to this message. Omitted or null when there are none.
`callDetails`	object	Yes	Present only when `contentType` is `CALL`. Otherwise omitted or null.

Reaction Object

Each entry in a message's reactions array:

Field	Type	Nullable	Description
`emoji`	string	No	The reaction emoji character.
`sender`	string	No	Who reacted: `visitor` for the end user or `agent` for a human agent.
`createdOn`	string	No	When the reaction was added, in ISO-8601 UTC.

A standalone message with content type REACT is an event marker with empty content. The emoji itself is carried in the reactions array of the message it reacts to.

Call Details Object

Present on CALL messages:

Field	Type	Nullable	Description
`callId`	string	No	Call identifier.
`direction`	string	No	`USER_INITIATED` or `AGENT_INITIATED`.
`status`	string	No	One of `RINGING`, `INITIATING`, `CONNECTING`, `CONNECTED`, `ACCEPTED`, `TERMINATED`, `REJECTED`, `MISSED`, `FAILED`, `AI_CONNECTED` or `UNKNOWN`.
`consumerPhone`	string	No	End user's phone number in E.164 form.
`businessPhone`	string	No	Business phone number in E.164 form.
`startedAt`	string	Yes	Call start time in ISO-8601 UTC, if known.
`endedAt`	string	Yes	Call end time in ISO-8601 UTC, if known.
`duration`	string	Yes	Call duration in seconds, if known.

Content TypesWhat the content field holds for each message type

Content Types

The content field is always a string. Its meaning depends on the contentType.

Content type	What content holds
`TEXT`	Plain UTF-8 text. This is the default and covers the vast majority of messages.
`JSON`	A stringified JSON payload, typically rich media such as an image, video, document, audio clip or sticker, or an interactive menu.
`TEMPLATE_MESSAGE`	A stringified JSON WhatsApp template or promotion message, with a header, body, footer, buttons and optional carousel cards.
`REACT`	An empty string. The message records an emoji reaction to an earlier message. There is no inline text payload.
`CALL`	An empty string. The message marks a voice-call event, for example a WhatsApp call. There is no inline text payload.

Sample: TEXT

Plain text, the default

{
  "messageId": "6690aa11bb22cc33dd44ee55",
  "sender": "visitor",
  "content": "Hi there, I need help with my order",
  "contentType": "TEXT",
  "createdOn": "2026-07-20T10:15:00Z"
}

Sample: JSON

Rich media, carried as a stringified JSON payload

{
  "messageId": "6690aa11bb22cc33dd44ee58",
  "sender": "bot",
  "content": "{\"type\":\"RICH_CONTENT\",\"image\":\"https://cdn.example.com/p.jpg\",\"caption\":\"Our new arrival\"}",
  "contentType": "JSON",
  "createdOn": "2026-07-20T10:16:10Z"
}

Sample: TEMPLATE_MESSAGE

A WhatsApp template or promotion message

{
  "messageId": "6690aa11bb22cc33dd44ee59",
  "sender": "bot",
  "content": "{\"header\":{\"type\":\"IMAGE\",\"mediaUrl\":\"https://cdn.example.com/promo.jpg\"},\"body\":\"Flash sale today!\",\"footer\":\"Reply STOP to opt out\",\"buttons\":[{\"type\":\"URL\",\"text\":\"Shop now\",\"url\":\"https://shop.example.com\"}]}",
  "contentType": "TEMPLATE_MESSAGE",
  "createdOn": "2026-07-20T10:17:00Z"
}

Sample: REACT

The reaction event itself carries empty content:

The reaction event marker

{
  "messageId": "6690aa11bb22cc33dd44ee5a",
  "sender": "agent",
  "content": "",
  "contentType": "REACT",
  "createdOn": "2026-07-20T10:18:00Z"
}

The earlier message it applies to then carries the emoji in its reactions array:

The message that was reacted to

{
  "messageId": "6690aa11bb22cc33dd44ee55",
  "sender": "visitor",
  "content": "Hi there, I need help with my order",
  "contentType": "TEXT",
  "createdOn": "2026-07-20T10:15:00Z",
  "reactions": [
    {
      "emoji": "<EMOJI_CHARACTER>",
      "sender": "agent",
      "createdOn": "2026-07-20T10:18:00Z"
    }
  ]
}

Sample: CALL

A voice-call event marker

{
  "messageId": "6690aa11bb22cc33dd44ee5b",
  "sender": "system",
  "content": "",
  "contentType": "CALL",
  "createdOn": "2026-07-20T10:19:00Z",
  "callDetails": {
    "callId": "wacid.HBgL...",
    "direction": "USER_INITIATED",
    "status": "TERMINATED",
    "consumerPhone": "+94771234567",
    "businessPhone": "+94112000000",
    "startedAt": "2026-07-20T10:19:05Z",
    "endedAt": "2026-07-20T10:21:35Z",
    "duration": "150"
  }
}

Reading the TranscriptWho sent what, in which order, and for how long it is kept

Senders, Ordering and Retention

Three behaviours determine how a conversation transcript should be read and displayed.

Sender Mapping

Internal role	API sender	Meaning
`user`	`visitor`	Message from the end user or contact.
`assistant`	`bot`	Automated persona reply.
`agent`	`agent`	Human agent reply.
`reader`	`system`	Rare system or internal marker.

Ordering

Within a session, messages are ascending by createdOn, oldest first.
Across sessions, ordering is descending by the session's latest message, so the most recent conversation comes first.
Pagination through page and limit is applied over session groups, not over individual messages.

Retention

Retention window Last 3 months

Only messages from the last three months are returned. This matches the admin Conversations screen.

Plan for the retention window

If you need a permanent archive of conversations, export and store them in your own system on a regular schedule. Messages older than three months are not available through this API.

Error HandlingStatus codes and the standard error body

Errors

All errors return a JSON body with a machine-readable code and a human-readable message.

Error Response Shape

JSON

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is missing or invalid."
  }
}

Status Codes

HTTP code	Code	When it happens
`400`	`BAD_REQUEST`	An invalid or missing query parameter, for example a missing `contactId` or a non-integer `page`.
`401`	`INVALID_API_KEY`	A missing, malformed, revoked or unscoped API key.
`403`	`FORBIDDEN`	The key is not permitted for this endpoint, method or enterprise.
`404`	`CONTACT_NOT_FOUND`	The `contactId` does not exist within your enterprise.
`429`	`RATE_LIMITED`	The per-key rate limit has been exceeded.
`500`	`INTERNAL_ERROR`	An unexpected server error.

Cross-tenant access is treated as not found, returning 404 rather than 403, so keys cannot be used to probe for other enterprises' contact IDs.

When reporting an issue, include the X-Correlation-ID header returned with the failing response.

Solutions By Channel

Developer Documentation

Build with Sprout

WhatsApp API Gateway

Business API v1

Which API do I need?

Getting Started

Sprout WhatsApp API Gateway

Main Capabilities

Message Template Management

Send Template Messages

Message Status Updates

Incoming Customer Messages

Getting Started

Looking for contact and conversation data?

Base URL

Host

API Path

Full Base URL

Authentication

Required Headers

Authorization

Content Type

Identifiers and Terminology

WhatsApp Business Account ID

WhatsApp Business Phone Number ID

Message Template ID

List Templates

Required Information

Response Information

Common Values

Paging

Example Request

Example Response

Create Template

Request Body Fields

Supported Template Components

Header

Body

Footer

Buttons

Response

Example Request

Example Response

Edit Template

Eligible Template Statuses

Editable Properties

Important Editing Rules

Response

Example Request

Example Response

Delete Template

Required Query Information

Message Template ID

Template Name

Required Information

Example Request

Example Response

Send Template Message

Request Body Fields

Template Configuration

Named Parameters

Response

Example Payload

Example Response

Reading this message back later

Message Status Updates

Documented Events

Sent Webhook Event

Payload Information

Documented Pricing Values

Example Webhook Payload

Delivered Webhook Event

Payload Information

Documented Pricing Values

Example Webhook Payload

Read Webhook Event

Payload Information

Documented Pricing Values

Example Webhook Payload