Send Interactive Messages

Send an interactive list menu or up to three quick-reply buttons.

Last updated 05 Aug 2026

Interactive messages let the recipient respond by tapping a button or selecting a row from a menu, instead of typing free text. There are two interactive types: list and button.

Endpoint

POST /messages.php

Shared fields

Field	Type	Required	Description
`to`	string	yes	Recipient's phone number, same format as Send a Text Message.
`type`	string	yes	Must be `"interactive"`.
`interactive.type`	string	yes	`"list"` or `"button"`.
`interactive.header.text`	string	no	1-60 characters. Only a text header is supported (no image/video headers).
`interactive.body.text`	string	yes	1-1024 characters.
`interactive.footer.text`	string	no	1-60 characters.

List messages

Field	Type	Required	Description
`interactive.action.button`	string	yes	Label of the button that opens the list, 1-20 characters.
`interactive.action.sections`	array	yes	1-10 sections. Combined, all sections may contain at most 10 rows in total.
`sections[].title`	string	no	1-24 characters.
`sections[].rows[].id`	string	yes	1-200 characters, unique across the whole message. Returned to you when the customer selects this row.
`sections[].rows[].title`	string	yes	1-24 characters.
`sections[].rows[].description`	string	no	1-72 characters.

curl -X POST "https://riffrechat.com/api/v1/messages.php" \
  -H "Authorization: Bearer rf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919876543210",
    "type": "interactive",
    "interactive": {
      "type": "list",
      "header": { "type": "text", "text": "Product options" },
      "body": { "text": "Choose a size to continue:" },
      "footer": { "text": "Prices include tax" },
      "action": {
        "button": "Select size",
        "sections": [
          {
            "title": "Available sizes",
            "rows": [
              { "id": "size-s", "title": "Small", "description": "In stock" },
              { "id": "size-m", "title": "Medium", "description": "In stock" },
              { "id": "size-l", "title": "Large", "description": "Only 2 left" }
            ]
          }
        ]
      }
    }
  }'

Button messages

Field	Type	Required	Description
`interactive.action.buttons`	array	yes	1-3 reply buttons.
`buttons[].type`	string	yes	Must be `"reply"`.
`buttons[].reply.id`	string	yes	1-256 characters, unique across the message. Returned to you when the customer taps this button.
`buttons[].reply.title`	string	yes	1-20 characters.

{
  "to": "919876543210",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": { "text": "Would you like to confirm this order?" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "confirm", "title": "Confirm" } },
        { "type": "reply", "reply": { "id": "cancel", "title": "Cancel" } }
      ]
    }
  }
}

Success response

Same shape as Send a Text Message: 202 Accepted with queue_id, status, status_label, charged, currency, balance_after, message_id and internal_queue_id.

Errors specific to interactive messages

`error` slug	Cause
`interactive_type_must_be_list_or_button`	`interactive.type` is missing or not `list`/`button`.
`interactive_list_requires_between_1_and_10_sections`	Zero or more than 10 sections.
`interactive_lists_support_at_most_10_rows_in_total`	More than 10 rows across all sections combined.
`list_row_ids_must_be_unique`	Two rows share the same `id`.
`interactive_button_messages_require_between_1_and_3_buttons`	Zero, or more than 3, buttons.
`reply_button_ids_must_be_unique`	Two buttons share the same `reply.id`.
`interactive_list_and_button_headers_must_be_text`	A header was supplied with a `type` other than `text`.

Riffre API Reference