> ## Documentation Index > Fetch the complete documentation index at: https://docs.automatebusiness.com/llms.txt > Use this file to discover all available pages before exploring further. # Send Interactive Message > Sends an interactive message (reply buttons, a list menu, a call-to-action URL button, an address request or a media carousel) or a location pin to a contact. This requires an active 24-hour Meta session window; outside it, use a template message instead. 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](https://docs.automatebusiness.com/automate-chats/api-reference/messages/send-message.md) 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](#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 ```bash Reply buttons theme={null} 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" } ] }' ``` ```bash List theme={null} 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" } ] } ] }' ``` ```bash CTA URL theme={null} 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" }' ``` ```bash Ask for address theme={null} 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 }' ``` ```bash Send location theme={null} 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`. ```bash Carousel with URL buttons theme={null} 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" } ] }' ``` ```bash Carousel with quick replies theme={null} 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. ## OpenAPI ````yaml POST /api/chat/message/interactive openapi: 3.1.0 info: title: Automate Chats API description: >- API for managing WhatsApp template messages, contacts, custom fields, tags, campaigns, and external integrations. version: 1.0.0 servers: - url: https://api.automatechats.com security: - apiKeyAuth: [] paths: /api/chat/message/interactive: post: summary: Send Interactive Message description: >- Sends an interactive message (reply buttons, a list menu, a call-to-action URL button, an address request or a media carousel) or a location pin to a contact. This requires an active 24-hour Meta session window; outside it, use a template message instead. requestBody: required: true content: application/json: schema: type: object required: - interactiveType properties: channel_id: type: string format: uuid description: >- Optional when you authenticate with an API key, because the key is already bound to a channel. conversationId: type: string description: >- Existing conversation ID. When sent, the recipient is resolved from the conversation. contactId: type: string description: >- Existing contact ID. When sent, the recipient is resolved from the contact. recipientPhoneNumber: type: string description: >- 7-15 digits, without country code. Required unless `conversationId` or `contactId` is sent. example: '9876543210' countryCode: type: string description: >- Country code, with or without `+`. Required unless `conversationId` or `contactId` is sent. example: '+91' interactiveType: type: string enum: - button - list - cta_url - address_message - carousel - location description: >- `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. body: type: string maxLength: 1024 description: >- Main message text. Required for every type except `location`. header: type: string maxLength: 60 description: >- Optional header text. Used for `list` and `cta_url`; for `button` it is sent only when provided. Not supported for `carousel`. footer: type: string maxLength: 60 description: Optional footer text. Not supported for `carousel`. buttons: type: array minItems: 1 maxItems: 3 items: type: object required: - id - title properties: id: type: string maxLength: 256 description: Returned to you when the user taps the button. example: btn_1 title: type: string maxLength: 20 example: 'Yes' description: >- Required for `button`. WhatsApp allows at most 3 reply buttons. buttonText: type: string maxLength: 20 description: >- 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. example: Choose sections: type: array minItems: 1 maxItems: 10 items: type: object required: - rows properties: title: type: string maxLength: 24 rows: type: array minItems: 1 maxItems: 10 items: type: object required: - id - title properties: id: type: string maxLength: 200 example: row_1 title: type: string maxLength: 24 example: Option 1 description: type: string maxLength: 72 description: Required for `list`. cards: type: array minItems: 2 maxItems: 10 items: type: object required: - headerType - mediaUrl properties: headerType: type: string enum: - image - video description: Type of the card header. mediaUrl: type: string format: uri description: >- Publicly reachable `http://` or `https://` URL of the image or video. example: https://cdn.example.com/blue-echeveria.jpg body: type: string maxLength: 160 description: >- Optional card text. Up to 160 characters and 2 line breaks. buttonText: type: string maxLength: 20 description: >- Label of the card's URL button. Send with `url`, and do not send `buttons` on the same card. example: Buy now url: type: string format: uri description: Link the URL button opens. Send with `buttonText`. example: https://shop.example.com/blue-echeveria buttons: type: array minItems: 1 items: type: object required: - id - title properties: id: type: string maxLength: 256 description: >- Returned to you when the customer taps the button. example: learn-blue-echeveria title: type: string maxLength: 20 example: Learn more description: >- Quick-reply buttons for this card. Use these or `buttonText` with `url`, not both. description: >- 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. url: type: string format: uri description: >- Required for `cta_url`. Must include `https://` or `http://`. example: https://example.com addressCountry: type: string enum: - IN - SG default: IN description: >- For `address_message`. Country of the address form. WhatsApp supports India and Singapore. addressValues: type: object description: >- For `address_message`. Optional values to pre-fill in the customer's address form. `phone_number` defaults to the recipient's number. properties: name: type: string maxLength: 200 phone_number: type: string example: '+919876543210' in_pin_code: type: string description: India only. sg_post_code: type: string description: Singapore only. house_number: type: string floor_number: type: string tower_number: type: string building_name: type: string address: type: string maxLength: 500 landmark_area: type: string city: type: string state: type: string autoFillAddress: type: boolean default: false description: >- 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: type: number minimum: -90 maximum: 90 description: Required for `location`. example: 18.5204 longitude: type: number minimum: -180 maximum: 180 description: Required for `location`. example: 73.8567 locationName: type: string maxLength: 100 description: For `location`. Place name. locationAddress: type: string maxLength: 200 description: For `location`. Street address. contextMessageId: type: string description: WhatsApp message ID to reply to. examples: Reply buttons: value: 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' List: value: interactiveType: list recipientPhoneNumber: '9876543210' countryCode: '+91' header: Support 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: value: interactiveType: cta_url recipientPhoneNumber: '9876543210' countryCode: '+91' body: Your invoice is ready. buttonText: View invoice url: https://example.com/invoice/123 Ask for address: value: interactiveType: address_message conversationId: 6a969ace3e8d1acd2659cff6 body: Please share your delivery address. addressCountry: IN autoFillAddress: true Send location: value: interactiveType: location recipientPhoneNumber: '9876543210' countryCode: '+91' latitude: 18.5204 longitude: 73.8567 locationName: Our store locationAddress: FC Road, Pune responses: '200': description: Message sent successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Message sent successfully data: type: object properties: messageId: type: string description: Internal message ID. whatsappMessageId: type: string example: wamid.HBgMOTE4NTYx... status: type: string example: sent '400': description: >- Validation error, for example more than 3 reply buttons, a missing `buttonText`, fewer than 2 or more than 10 carousel cards, carousel cards with different button types, or the 24-hour session window has expired. '401': $ref: '#/components/responses/UnauthorizedError' components: responses: UnauthorizedError: description: Unauthorized (missing or invalid API key / JWT token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: error code: 401 message: >- Unauthorized access: Invalid or missing authentication credentials. timestamp: '2026-05-18T15:00:00.000Z' schemas: ErrorResponse: type: object properties: status: type: string example: error code: type: integer example: 400 message: type: string example: 'Invalid input: field first_name is required.' error: description: Optional validation error details or raw stack traces. timestamp: type: string format: date-time example: '2026-05-18T15:00:00.000Z' securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.