8x8 Business Messaging (Chat Apps) API for sending and receiving rich messages over WhatsApp Business, RCS, Viber Business, LINE Official Account, Zalo ZNS and other chat channels.
{
"openapi": "3.0.0",
"info": {
"title": "Business Messaging API",
"version": "1",
"description": "This API is for sending messages in Messaging Apps like WhatsApp, Viber, RCS and Line. It also provides the ability to manage templates and export logs.",
"contact": {
"name": "8x8 Inc",
"url": "https://cpaas.8x8.com",
"email": "cpaas-support@8x8.com"
},
"termsOfService": "https://cpaas.8x8.com/sg/terms-and-conditions/"
},
"servers": [
{
"url": "https://chatapps.8x8.com",
"description": "Asia-Pacific region"
},
{
"url": "https://chatapps.us.8x8.com",
"description": "North America region"
},
{
"url": "https://chatapps.8x8.uk",
"description": "Europe region"
},
{
"url": "https://chatapps.8x8.id",
"description": "Indonesia region"
}
],
"tags": [
{
"name": "Send Message API"
},
{
"name": "Send Message Event API"
},
{
"name": "Management API"
},
{
"name": "Reporting API"
},
{
"name": "Webhook Configuration API"
},
{
"name": "File Upload API"
}
],
"paths": {
"/api/v1/subaccounts/{subAccountId}/messages": {
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1subaccounts~1%7BsubAccountId%7D~1lon/parameters/0"
}
],
"post": {
"responses": {
"200": {
"description": "Success response",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1api~1v1~1subaccounts~1%7BsubAccountId%7D~1lon/post/responses/200/content/application~1json/schema"
},
"examples": {
"response": {
"value": {
"umid": "82188ee0-109f-e811-8150-020897df5459",
"user": {
"msisdn": "+6512341234"
},
"clientMessageId": "1234_id",
"status": {
"state": "queued",
"timestamp": "2021-01-04T08:19:45.99Z"
}
}
}
}
}
}
},
"400": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1webhooks/get/responses/400"
},
"401": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1webhooks/get/responses/401"
},
"500": {
"$ref": "#/paths/~1files~1%7Bfilename%7D/get/responses/500"
}
},
"operationId": "Send-Message",
"summary": "Send message",
"tags": [
"Send Message API"
],
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1subaccounts~1%7BsubAccountId%7D~1lon/parameters/0"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"user": {
"msisdn": "+6500000000",
"channelUserId": "US.13491208655302741918"
},
"clientMessageId": "1234_id",
"type": "Image",
"content": {
"text": "Welcome to Singapore!",
"url": "https://pbs.twimg.com/media/Dd8E0yjV0AYdxd4.jpg",
"fallbackText": "We tried to send an image - but Welcome to Singapore",
"sms": {
"encoding": "AUTO",
"source": "SENDERID"
}
}
},
"properties": {
"user": {
"type": "object",
"description": "User information\n",
"title": "User",
"properties": {
"msisdn": {
"type": "string",
"description": "Mobile phone number (MSISDN) to send the message to. International phone number format with '+ sign prefered. In addition we support national (local) phone numbers, please set `country` field to use it.",
"example": "+6500000000"
},
"country": {
"type": "string",
"maxLength": 2,
"description": "Default country code (like 'sg', 'uk') for national phone numbers format. You don't need it if `msisdn` in E.164 format (with '+' sign at the beginning)",
"example": "SG"
},
"lineUserId": {
"type": "string",
"description": "LINE user ID of the recipient. Use this instead of `msisdn` when sending messages to a LINE user via the Line Official Account channel.",
"example": "Ua12b345678c1de0fg1a1234567891011"
},
"channelUserId": {
"type": "string",
"description": "WhatsApp Business-Scoped User ID (BSUID) of the recipient. Format: `<ISO-3166-alpha-2-country-code>.<alphanumeric>` (country code must be uppercase). Can be used alongside `msisdn`; if both are provided, `msisdn` takes precedence.",
"example": "US.13491208655302741918"
}
}
},
"clientMessageId": {
"type": "string",
"description": "Client managed id for the message : your own unique reference",
"maxLength": 50,
"example": "abc-123"
},
"type": {
"type": "string",
"enum": [
"text",
"audio",
"video",
"image",
"location",
"file",
"interactive",
"template",
"carousel",
"richCard"
],
"description": "Messaging Apps message content type.\nAllowed values are \"text\", \"image\", \"audio\", \"video\", \"file\", \"location\", \"interactive\", \"template\", \"carousel\" and \"richCard\".\n- If the type is \"text\", then content object should contain a \"text\" parameter.\n- If the type is \"image\", \"audio\", \"video\" or \"file\", then content object should contain a \"url\" parameter and all other parameters can be used.\n- If the type is \"location\", then content object should contain a \"latitude\", \"longitude\" parameters.\n- If the type is \"interactive\", then content object should contain an \"interactive\" parameter.\n- If the type is \"template\", then content object should contain a \"template\" parameter.\n- If the type is \"carousel\", then content object should contain a \"carousel\" parameter. Supported for RCS channel only.\n- If the type is \"richCard\", then content object should contain a \"richCard\" parameter. Supported for RCS channel only.",
"example": "Text",
"title": "Content type"
},
"content": {
"type": "object",
"description": "Content of the message",
"title": "Content",
"properties": {
"text": {
"type": "string",
"description": "Message body - the text of the message\n",
"maxLength": 35000,
"example": "Hello"
},
"whatsApp": {
"type": "object",
"description": "WhatsApp-specific message settings. Only applies when the message is delivered via the WhatsApp channel.",
"title": "WhatsApp settings",
"properties": {
"directSend": {
"type": "object",
"description": "WhatsApp Direct Send settings. When this object is present, the message is sent using the WhatsApp Direct Send API instead of a pre-created template. Direct Send allows you to send business-initiated utility messages without pre-creating a template; matching templates are auto-generated and managed on your behalf.\n\nDirect Send supports the following message subset:\n- `text` messages.\n- `interactive` messages of type `cta_url`, with a single Call-to-Action URL button defined via `interactive.action.parameters`.\n- `interactive` messages of type `button` (Reply Buttons), with 1–3 buttons.\n- For `interactive` messages, only `text` headers are supported.",
"title": "WhatsApp Direct Send settings",
"properties": {
"category": {
"type": "string",
"description": "Required. Indicates the category of the message to be sent as an auto-generated template. Currently only `utility` is supported; messages will be charged at utility rates.",
"enum": [
"utility"
],
"example": "utility"
},
"ttlSeconds": {
"type": "integer",
"description": "Optional Time-to-live (TTL) in seconds for the message. If the message cannot be delivered within this window, it is dropped. Defaults to 30 days. Minimum 30 seconds, maximum 43200 seconds (12 hours).",
"minimum": 30,
"maximum": 43200,
"example": 600
}
},
"required": [
"category"
]
}
}
},
"url": {
"type": "string",
"description": "Public URL of where the rich content is stored.",
"format": "uri",
"example": "http://example.com"
},
"fallbackText": {
"type": "string",
"description": "In case SMS fallback is triggered, message body - the text of the message",
"maxLength": 35000,
"example": "you can check your account by http://example.com"
},
"sms": {
"type": "object",
"description": "If the SMS fallback is triggered, here are the SMS settings",
"properties": {
"encoding": {
"$ref": "#/paths/~1api~1v1~1subaccounts~1%7BsubAccountId%7D~1lon/post/requestBody/content/application~1json/schema/properties/smsFallback/properties/encoding"
},
"source": {
"type": "string",
"description": "Source number (SenderId) - \"From\" field for SMS. Max length 16 chars.",
"maxLength": 16,
"example": "Info"
}
},
"title": "SMS content settings"
},
"location": {
"type": "object",
"description": "Location object. Required for \"location\" type",
"properties": {
"latitude": {
"type": "number",
"example": 12.345,
"description": "Latitude"
},
"longitude": {
"type": "number",
"example": 12.345,
"description": "Longitude"
},
"name": {
"type": "string",
"example": "Pablo Morales",
"description": "Text that will appear below the generic map at the top of the message"
},
"address": {
"type": "string",
"example": "1 Hacker Way, Menlo Park, CA 94025",
"description": "Address that will appear below the generic map at the top of the message"
}
},
"required": [
"latitude",
"longitude"
],
"title": "Location data"
},
"interactive": {
"type": "object",
"description": "This is an interactive message. Type and Action are required properties",
"properties": {
"type": {
"type": "string",
"example": "button",
"enum": [
"button",
"list",
"product",
"product_list",
"cta_url",
"flow",
"call_permission_request",
"request_contact_info",
"voice_call",
"location_request_message"
],
"description": "The type of interactive message you want to send."
},
"action": {
"type": "object",
"description": "Action you want the user to perform after reading the message.",
"properties": {
"button": {
"type": "string",
"description": "Required for List Messages.\n\nButton content. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not.",
"maxLength": 20
},
"buttons": {
"type": "array",
"description": "Required for Reply Buttons.",
"maxItems": 3,
"uniqueItems": true,
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "reply",
"enum": [
"reply"
],
"description": "Type of button"
},
"reply": {
"type": "object",
"description": "The id and title properties are required.",
"properties": {
"id": {
"type": "string",
"maxLength": 256,
"description": "Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user."
},
"title": {
"type": "string",
"description": "Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not.",
"maxLength": 20
}
}
}
}
}
},
"catalog_id": {
"type": "string",
"description": "Required for Single Product Messages and Multi-Product Messages.\n\nUnique identifier of the Facebook catalog linked to your WhatsApp Business Account."
},
"product_retailer_id": {
"type": "string",
"description": "Required for Single Product Messages and Multi-Product Messages.\n\nUnique identifier of the product in a catalog."
},
"name": {
"type": "string",
"description": "Required to be `send_location` for Location Request Message."
},
"sections": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Array of section objects. ",
"items": {
"type": "object",
"properties": {
"rows": {
"type": "array",
"description": "Required for List Messages.\n\nContains a list of rows. You can have a total of 10 rows across your sections.\n\nThe id and title properties are required.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"maxLength": 200
},
"title": {
"type": "string",
"maxLength": 24
},
"description": {
"type": "string",
"maxLength": 72
}
}
}
},
"product_items": {
"type": "array",
"description": "Required for Multi-Product Messages.\n\nArray of product objects. There is a minimum of 1 product per section and a maximum of 30 products across all sections.",
"items": {
"type": "object",
"properties": {
"product_retailer_id": {
"type": "string",
"description": "Required for Multi-Product Messages. Unique identifier of the product in a catalog. The product_retailer_id property is required."
}
}
}
},
"title": {
"type": "string",
"maxLength": 24,
"description": "Required if the message has more than one section.\n\nTitle of the section."
}
}
}
},
"parameters": {
"type": "object",
"description": "Required for Call-to-Action Url (`cta_url`) and `voice_call` messages.",
"properties": {
"display_text": {
"type": "string",
"description": "CTA Url button label text. For `voice_call`, this is the label shown on the call button. Optional; defaults to \"Call Now\" if omitted. Max 20 characters.",
"maxLength": 20
},
"ttlMinutes": {
"type": "integer",
"description": "Optional for `voice_call` only. Overrides the template-level TTL at send time. Must be between 1 min and 43200 mins (30 days). Defaults to 10080 (7 days) if omitted.",
"minimum": 1,
"maximum": 43200,
"default": 10080,
"example": 10
},
"payload": {
"type": "string",
"description": "Optional for `voice_call`. Customer-defined payload. Max 512 characters.",
"maxLength": 512
},
"url": {
"type": "string",
"description": "URL to load in the device's default web browser when tapped by user."
},
"flowId": {
"type": "string",
"description": "Required for Flow messages. Unique ID of the Flow provided by WhatsApp.",
"example": "859504979861628"
},
"flowCta": {
"type": "string",
"description": "Required for Flow messages. Text on the CTA button. For example: \"Signup\". CTA text length is advised to be 30 characters or less (no emoji).",
"maxLength": 30,
"example": "Get Recommendations"
},
"flowAction": {
"type": "string",
"description": "Optional for Flow messages. Either \"navigate\" or \"data_exchange\". Defaults to \"navigate\" if not provided.",
"enum": [
"navigate",
"data_exchange"
],
"default": "navigate",
"example": "navigate"
},
"flowActionPayload": {
"type": "object",
"description": "Optional for Flow messages. Should only be used when flowAction is \"navigate\". Should be omitted otherwise.",
"properties": {
"screen": {
"type": "string",
"description": "Optional. The ID of the screen displayed first. It needs to be an entry screen. Defaults to \"FIRST_ENTRY_SCREEN\" if not provided.",
"default": "FIRST_ENTRY_SCREEN",
"example": "RECOMMEND"
},
"data": {
"type": "object",
"description": "Optional. Input data for the first Screen of the Flow. If provided, this must be a non-empty object. Defaults to null if not provided.",
"additionalProperties": true,
"example": {
"product_id": "12345",
"user_name": "John Doe",
"campaign_id": "summer_sale_2024"
}
}
}
}
}
}
}
},
"header": {
"type": "object",
"description": "Header content displayed on top of a message. You cannot set a header if your interactive object is of product and location request message type.",
"properties": {
"document": {
"$ref": "#/paths/~1api~1v1~1subaccounts~1%7BsubAccountId%7D~1messages/post/requestBody/content/application~1json/schema/properties/content/properties/interactive/properties/header/properties/text"
},
"image": {
"$ref": "#/paths/~1api~1v1~1subaccounts~1%7BsubAccountId%7D~1messages/post/requestBody/content/application~1json/schema/properties/content/properties/interactive/properties/header/properties/text"
},
"text": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Required when type is audio, document, image, sticker, or video and you are not using a link.\n\nThe media object ID. Do not use this field when message type is set to text."
},
"link": {
"type": "string",
"description": "Required when type is audio, document, image, sticker, or video and you are not using an uploaded media ID (i.e. you are hosting the media asset on your server).\n\nThe protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs."
},
"caption": {
"type": "string",
"description": "Describes the specified image, document, or video media.\n\n\nDo not use with audio or sticker media."
},
"filename": {
"type": "string",
"description": "Describes the filename for the specific document. Use only with document media.\n\nThe extension of the filename will specify what format the document is displayed as in WhatsApp."
},
"provider": {
"type": "string",
"deprecated": true,
"description": "This path is optionally used with a link when the HTTP/HTTPS link is not directly accessible and requires additional configurations like a bearer token."
}
},
"description": ""
},
"type": {
"type": "string",
"example": "text",
"enum": [
"text",
"video",
"image",
"document"
],
"description": "The header type you would like to use. The type property is required."
},
"video": {
"$ref": "#/paths/~1api~1v1~1subaccounts~1%7BsubAccountId%7D~1messages/post/requestBody/content/application~1json/schema/properties/content/properties/interactive/properties/header/properties/text"
}
}
},
"body": {
"type": "object",
"description": "Optional for type 'product', 'call_permission_request', and 'request_contact_info'. Required for other message types.\n\nAn object with the body of the message.",
"properties": {
"text": {
"type": "string",
"description": "The content of the message. Emojis and markdown are supported. The text property is required.",
"maxLength": 1024
}
}
},
"footer": {
"type": "object",
"description": "An object with the footer of the message. You cannot set a footer for location request message type",
"properties": {
"text": {
"type": "string",
"maxLength": 60,
"description": "The footer content. Emojis, markdown, and links are supported. The text property is required."
}
}
}
}
},
"video": {
"type": "object",
"description": "Video object. Required for \"video\" type",
"properties": {
"thumbnail": {
"type": "string",
"example": "http://example.com/video.jpg",
"description": "ThumbNail"
},
"filesize": {
"type": "number",
"example": 120,
"description": "Video File Size (in bytes)"
},
"duration": {
"type": "number",
"example": 10,
"description": "Duration of video (in seconds)"
}
},
"title": "Video data"
},
"image": {
"type": "object",
"description": "Image object. Used for Line channel to specify thumbnail for image messages.",
"properties": {
"thumbnail": {
"type": "string",
"example": "https://www.example.com/thumbnail.jpg",
# --- truncated at 32 KB (341 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/8x8/refs/heads/main/openapi/8x8-connect-business-messaging-api.json