Send Interactive Message

POST

api

chat

message

interactive

curl --request POST \
  --url https://api.automatechats.com/api/chat/message/interactive \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "interactiveType": "button",
  "conversationId": "6a969ace3e8d1acd2659cff6",
  "body": "Do you want to confirm your order?",
  "footer": "Reply to continue",
  "buttons": [
    {
      "id": "yes",
      "title": "Yes"
    },
    {
      "id": "no",
      "title": "No"
    }
  ]
}
'

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "messageId": "<string>",
    "whatsappMessageId": "wamid.HBgMOTE4NTYx...",
    "status": "sent"
  }
}

{
  "status": "error",
  "code": 401,
  "message": "Unauthorized access: Invalid or missing authentication credentials.",
  "timestamp": "2026-05-18T15:00:00.000Z"
}

Sends an interactive message to a contact: reply buttons, a list menu, a call-to-action URL button, a swipeable carousel of image or video cards, or a request for a delivery address. It can also send a location pin. Important: This endpoint requires an open 24-hour Meta session window (the user must have messaged your business within the last 24 hours). If the session has expired, use a Template Message instead.

Message types

`interactiveType`	Required fields	Limits
`button`	`body`, `buttons`	Up to 3 buttons, 20 characters per title
`list`	`body`, `buttonText`, `sections`	Up to 10 rows, 24 characters per row title, 72 per description
`cta_url`	`body`, `buttonText`, `url`	`url` must start with `http://` or `https://`
`carousel`	`body`, `cards`	2 to 10 cards. `header`, `footer` and `buttonText` are not used. See Sending a carousel
`address_message`	`body`	Optional `addressCountry` (`IN` or `SG`, default `IN`), `addressValues` and `autoFillAddress`
`location`	`latitude`, `longitude`	Optional `locationName` (100 characters) and `locationAddress` (200 characters). `body` is not used

header and footer are optional (60 characters each) for every type except location and carousel. body can be up to 1024 characters.

Choosing the recipient

Send either recipientPhoneNumber with countryCode, or an existing conversationId or contactId. When you send a conversation or contact ID, the recipient is resolved for you. When you authenticate with an API key, the message is sent from the channel the key is bound to. You do not need to send channel_id.

Examples

Reply buttons

curl -X POST https://api.automatechats.com/api/chat/message/interactive \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "interactiveType": "button",
    "recipientPhoneNumber": "9876543210",
    "countryCode": "+91",
    "body": "Do you want to confirm your order?",
    "buttons": [
      { "id": "yes", "title": "Yes" },
      { "id": "no", "title": "No" }
    ]
  }'

List

curl -X POST https://api.automatechats.com/api/chat/message/interactive \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "interactiveType": "list",
    "recipientPhoneNumber": "9876543210",
    "countryCode": "+91",
    "body": "What do you need help with?",
    "buttonText": "Choose",
    "sections": [
      { "title": "Topics", "rows": [
        { "id": "orders", "title": "My orders", "description": "Track or cancel" },
        { "id": "billing", "title": "Billing" }
      ] }
    ]
  }'

CTA URL

curl -X POST https://api.automatechats.com/api/chat/message/interactive \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "interactiveType": "cta_url",
    "recipientPhoneNumber": "9876543210",
    "countryCode": "+91",
    "body": "Your invoice is ready.",
    "buttonText": "View invoice",
    "url": "https://example.com/invoice/123"
  }'

Ask for address

curl -X POST https://api.automatechats.com/api/chat/message/interactive \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "interactiveType": "address_message",
    "conversationId": "6a969ace3e8d1acd2659cff6",
    "body": "Please share your delivery address.",
    "addressCountry": "IN",
    "autoFillAddress": true
  }'

Send location

curl -X POST https://api.automatechats.com/api/chat/message/interactive \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "interactiveType": "location",
    "recipientPhoneNumber": "9876543210",
    "countryCode": "+91",
    "latitude": 18.5204,
    "longitude": 73.8567,
    "locationName": "Our store",
    "locationAddress": "FC Road, Pune"
  }'

Sending a carousel

A carousel shows a row of cards the customer can swipe. body is the message above the cards. Each item in cards has:

Field	Required	Description
`headerType`	Yes	`image` or `video`
`mediaUrl`	Yes	Public `http://` or `https://` URL of the image or video
`body`	No	Card text, up to 160 characters and 2 line breaks
`buttonText` and `url`	For a URL button	Button label (20 characters) and the link it opens
`buttons`	For quick replies	A list of `{ "id", "title" }`. Title is up to 20 characters, `id` up to 256

Each card has either one URL button or one or more quick-reply buttons, never both. All cards must use the same kind of button and the same number of buttons. The API returns a 400 error before sending if the cards do not match. When a customer taps a quick-reply button, you receive an incoming interactive reply that carries that button’s id.

Carousel with URL buttons

curl -X POST https://api.automatechats.com/api/chat/message/interactive \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "interactiveType": "carousel",
    "conversationId": "6a969ace3e8d1acd2659cff6",
    "body": "Here are three of our latest arrivals:",
    "cards": [
      {
        "headerType": "image",
        "mediaUrl": "https://cdn.example.com/blue-echeveria.jpg",
        "body": "*Blue Echeveria*",
        "buttonText": "Buy now",
        "url": "https://shop.example.com/blue-echeveria"
      },
      {
        "headerType": "image",
        "mediaUrl": "https://cdn.example.com/zebra-haworthia.jpg",
        "body": "*Zebra Haworthia*",
        "buttonText": "Buy now",
        "url": "https://shop.example.com/zebra-haworthia"
      }
    ]
  }'

Carousel with quick replies

curl -X POST https://api.automatechats.com/api/chat/message/interactive \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "interactiveType": "carousel",
    "conversationId": "6a969ace3e8d1acd2659cff6",
    "body": "Pick a plant:",
    "cards": [
      {
        "headerType": "image",
        "mediaUrl": "https://cdn.example.com/a.jpg",
        "buttons": [
          { "id": "learn-a", "title": "Learn more" },
          { "id": "fav-a", "title": "Add to favorites" }
        ]
      },
      {
        "headerType": "video",
        "mediaUrl": "https://cdn.example.com/b.mp4",
        "buttons": [
          { "id": "learn-b", "title": "Learn more" },
          { "id": "fav-b", "title": "Add to favorites" }
        ]
      }
    ]
  }'

Asking for an address

An address_message shows the customer a Provide address button that opens WhatsApp’s address form. The form works for India (IN) and Singapore (SG) numbers only. Use addressValues to pre-fill fields such as name, city, state and in_pin_code (or sg_post_code). Set autoFillAddress to true to pre-fill the contact’s name and the last address they shared in the conversation; this needs conversationId. When the customer submits the form, their answer arrives as an incoming interactive message and appears in the conversation as an address card.

Authorizations

X-API-Key

string

header

required

Body

application/json

interactiveType

enum<string>

required

button for reply buttons, list for a list menu, cta_url for a call-to-action link button, address_message to ask the customer for a delivery address, location to send a map pin. carousel to send 2 to 10 swipeable image or video cards.

Available options:

button,

list,

cta_url,

address_message,

carousel,

location

channel_id

string<uuid>

Optional when you authenticate with an API key, because the key is already bound to a channel.

conversationId

string

Existing conversation ID. When sent, the recipient is resolved from the conversation.

contactId

string

Existing contact ID. When sent, the recipient is resolved from the contact.

recipientPhoneNumber

string

7-15 digits, without country code. Required unless conversationId or contactId is sent.

Example:

"9876543210"

countryCode

string

Country code, with or without +. Required unless conversationId or contactId is sent.

Example:

"+91"

body

string

Main message text. Required for every type except location.

Maximum string length: 1024

header

string

Optional header text. Used for list and cta_url; for button it is sent only when provided. Not supported for carousel.

Maximum string length: 60

footer

string

Optional footer text. Not supported for carousel.

Maximum string length: 60

buttons

object[]

Required for button. WhatsApp allows at most 3 reply buttons.

Required array length: 1 - 3 elements

Show child attributes

buttonText

string

Required for list and cta_url. Label of the button that opens the list or link. Not used for carousel; set the button on each card instead.

Maximum string length: 20

Example:

"Choose"

sections

object[]

Required for list.

Required array length: 1 - 10 elements

Show child attributes

cards

object[]

Required for carousel. 2 to 10 cards. Every card needs the same kind of button: either one URL button on all cards, or the same number of quick-reply buttons on all cards.

Required array length: 2 - 10 elements

Show child attributes

url

string<uri>

Required for cta_url. Must include https:// or http://.

Example:

"https://example.com"

addressCountry

enum<string>

default:IN

For address_message. Country of the address form. WhatsApp supports India and Singapore.

Available options:

IN,

SG

addressValues

object

For address_message. Optional values to pre-fill in the customer's address form. phone_number defaults to the recipient's number.

Show child attributes

autoFillAddress

boolean

default:false

For address_message. Pre-fill from the customer's last shared address in the conversation (requires conversationId) and the contact name. Values in addressValues take priority.

latitude

number

Required for location.

Required range: -90 <= x <= 90

Example:

18.5204

longitude

number

Required for location.

Required range: -180 <= x <= 180

Example:

73.8567

locationName

string

For location. Place name.

Maximum string length: 100

locationAddress

string

For location. Street address.

Maximum string length: 200

contextMessageId

string

WhatsApp message ID to reply to.

Response

Message sent successfully

success

boolean

Example:

true

message

string

Example:

"Message sent successfully"

data

object

Show child attributes

curl --request POST \
  --url https://api.automatechats.com/api/chat/message/interactive \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "interactiveType": "button",
  "conversationId": "6a969ace3e8d1acd2659cff6",
  "body": "Do you want to confirm your order?",
  "footer": "Reply to continue",
  "buttons": [
    {
      "id": "yes",
      "title": "Yes"
    },
    {
      "id": "no",
      "title": "No"
    }
  ]
}
'

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "messageId": "<string>",
    "whatsappMessageId": "wamid.HBgMOTE4NTYx...",
    "status": "sent"
  }
}

{
  "status": "error",
  "code": 401,
  "message": "Unauthorized access: Invalid or missing authentication credentials.",
  "timestamp": "2026-05-18T15:00:00.000Z"
}

Getting Started

Core Features

API Reference

Message types

Choosing the recipient

Examples

Sending a carousel

Asking for an address

Authorizations

Body

Response

​Message types

​Choosing the recipient

​Examples

​Sending a carousel

​Asking for an address

Authorizations

Body

Response

Message types

Choosing the recipient

Examples

Sending a carousel

Asking for an address