---
updatedAt: 2026-10-30T08:35:21.000Z
agentTools:
  projectIndex: https://docs.wati.io/llms.txt
---

# Send Interactive Buttons Message

Compatibility reference for existing integrations. Use type=buttons with button_message. Recommended V3 route: `/api/ext/v3/conversations/messages/interactive`.

- Status code 200 means the message was accepted by WATI, not delivered yet.
- To know if a message is failed, listen to the **Session Message Failed** webhook.
- To know if a message is sent successfully, listen to Delivered/Read/Reply webhooks.

### Permissions

For API access tokens and OIDC tokens, satisfy **at least one** of: `api`, `wati_integration:write`, `conversations:write`. API access tokens may satisfy a listed scope through the configured scope hierarchy; OIDC tokens are checked against their scope claims. Legacy JWT authentication does not use this scope check. Authentication, role, tenant, and applicable feature or plan checks still apply. For HTTP 403, check the credential type, applicable scopes, roles, and workspace access; 403 does not always mean a missing scope. Authentication/authorization failures do not guarantee a JSON response body.

# OpenAPI definition

```json
{
  "openapi": "3.0.4",
  "info": {
    "title": "WATI API",
    "version": "2.6",
    "description": "Documentation contract version 2.6. Use V3 for supported business operations, adopting its request, response, defaults and pagination. Retain V1/V2 only for the business exceptions listed in Introduction. API route versions are independent of this artifact version.\n\nSend Authorization: Bearer <your-token> with the workspace credential and regional API host. API route version does not select the authentication mechanism. Endpoint scopes, roles, account availability and channel access still apply; consult Authentication and each operation.\n\nChannel support is operation-specific. GET /api/ext/v3/channels lists additional connected channels and may exclude the default WhatsApp number; do not infer full channel coverage or permission to send from discovery alone.\n\nInspect HTTP status and business result separately. Some operations report business failure or partial recipient failure in HTTP 200. Authorization errors may have no JSON body. A 429 can indicate a rate or usage limit. For unknown write outcomes, reconcile state before retrying; do not assume idempotency.\n\nCreate webhook subscriptions through the documented V2 exception or the dashboard, then manage them through V3. Use supported event types for the workspace and distinguish request acceptance from final message delivery.",
    "contact": {
      "name": "WATI Support",
      "url": "https://docs.wati.io"
    }
  },
  "servers": [
    {
      "url": "https://live-mt-server.wati.io",
      "description": "WATI API host. Legacy v1 and v2 endpoints require tenantId in the path; v3 endpoints do not."
    }
  ],
  "tags": [
    {
      "name": "Messages (v1)",
      "description": "Send and retrieve WhatsApp messages via the v1 API."
    }
  ],
  "paths": {
    "/{tenantId}/api/v1/sendInteractiveButtonsMessage": {
      "post": {
        "tags": [
          "Messages (v1)"
        ],
        "summary": "Send Interactive Buttons Message",
        "description": "Compatibility reference for existing integrations. Use type=buttons with button_message. Recommended V3 route: `/api/ext/v3/conversations/messages/interactive`.\n\n- Status code 200 means the message was accepted by WATI, not delivered yet.\n- To know if a message is failed, listen to the **Session Message Failed** webhook.\n- To know if a message is sent successfully, listen to Delivered/Read/Reply webhooks.\n\n### Permissions\n\nFor API access tokens and OIDC tokens, satisfy **at least one** of: `api`, `wati_integration:write`, `conversations:write`. API access tokens may satisfy a listed scope through the configured scope hierarchy; OIDC tokens are checked against their scope claims. Legacy JWT authentication does not use this scope check. Authentication, role, tenant, and applicable feature or plan checks still apply. For HTTP 403, check the credential type, applicable scopes, roles, and workspace access; 403 does not always mean a missing scope. Authentication/authorization failures do not guarantee a JSON response body.",
        "operationId": "SendInteractiveButtonsMessage",
        "parameters": [
          {
            "name": "whatsappNumber",
            "in": "query",
            "description": "WhatsApp Number with country code. Example, 85264318721. Optional when `target` is provided.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "target",
            "in": "query",
            "description": "Polymorphic recipient identifier. Accepts a phone number, ContactId, or BSUID. When provided, takes precedence over `whatsappNumber`. BSUID resolution depends on availability for your workspace.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "channelPhoneNumber",
            "in": "query",
            "description": "Channel phone number with country code. Example, 85264318722",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tenantId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Your WATI workspace (tenant) ID. This required path segment identifies the WATI account for legacy v1 and v2 API requests."
          }
        ],
        "requestBody": {
          "description": "**InteractiveButtonsMessage**\n            \n**Header:**\n{\n  \"type\": \"**Text** or **Video** or **Image** or **Document**\",\n  \"text\": \"header text for type **Text**\",\n  \"media\": {\n    \"url\": \"https://...\",        // (media obj should be not empty for non **Text** types)\n    \"fileName\": \"MyDoc.pdf\" }     // (this field is only **Document** type)\n}\n            \n**Buttons:**\n- allowed count: **1–3**\n- **Allowed characters length after mapping:**\n  - header text: **60**\n  - body text: **1024**\n  - footer text: **60**\n  - button's text: **20**",
          "content": {
            "application/json-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/ButtonsMessage"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ButtonsMessage"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/ButtonsMessage"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/ButtonsMessage"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/InteractiveMessageV1Response"
                },
                "example": {
                  "ok": true,
                  "errors": null,
                  "message": {
                    "id": "gBEGkFNjWCNiAglMS4Q4Em0CeXC",
                    "type": "interactive",
                    "created": "2024-01-15T10:32:00Z"
                  },
                  "info": null
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InteractiveMessageV1Response"
                },
                "example": {
                  "ok": true,
                  "errors": null,
                  "message": {
                    "id": "gBEGkFNjWCNiAglMS4Q4Em0CeXC",
                    "type": "interactive",
                    "created": "2024-01-15T10:32:00Z"
                  },
                  "info": null
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/InteractiveMessageV1Response"
                },
                "example": {
                  "ok": true,
                  "errors": null,
                  "message": {
                    "id": "gBEGkFNjWCNiAglMS4Q4Em0CeXC",
                    "type": "interactive",
                    "created": "2024-01-15T10:32:00Z"
                  },
                  "info": null
                }
              }
            }
          },
          "403": {
            "description": "Authorization failed. Check the Permissions section for the credential-specific scope rules, and check roles and workspace access. The response may have no body; do not require a JSON error envelope."
          }
        },
        "x-wati-permissions": {
          "scopeRequirementGroups": [
            {
              "anyOf": [
                "api",
                "wati_integration:write",
                "conversations:write"
              ]
            }
          ],
          "groupOperator": "allOf",
          "appliesTo": [
            "ApiAccessToken",
            "OIDC"
          ],
          "legacyJwtScopeCheck": "skipped",
          "apiAccessTokenHierarchy": "configured-by-identity-provider",
          "oidcFallbackWhenNoEndpointScope": null,
          "sourceCommit": "03c6d4bc1590408c569e65602f969c6a596672e3"
        },
        "x-wati-documentation": {
          "discovery": "compatibility-link-only",
          "recommendedPath": "/api/ext/v3/conversations/messages/interactive",
          "reason": "Use type=buttons with button_message."
        },
        "x-internal": true
      }
    }
  },
  "components": {
    "schemas": {
      "ButtonsMessage": {
        "type": "object",
        "properties": {
          "body": {
            "type": "string",
            "nullable": true,
            "maxLength": 1024,
            "minLength": 0
          },
          "footer": {
            "type": "string",
            "nullable": true,
            "maxLength": 60,
            "minLength": 0
          },
          "header": {
            "$ref": "#/components/schemas/ButtonsMessageHeader"
          },
          "buttons": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ButtonsMessageButtons"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ButtonsMessageButtons": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "nullable": true,
            "maxLength": 20,
            "minLength": 0
          }
        },
        "additionalProperties": false
      },
      "ButtonsMessageHeader": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "nullable": true,
            "maxLength": 60,
            "minLength": 0
          },
          "type": {
            "type": "string",
            "nullable": true
          },
          "media": {
            "$ref": "#/components/schemas/ButtonsMessageHeaderMedia"
          }
        },
        "additionalProperties": false
      },
      "ButtonsMessageHeaderMedia": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "nullable": true
          },
          "fileName": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "InteractiveMessageV1Response": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "errors": {
            "nullable": true
          },
          "message": {
            "nullable": true
          },
          "info": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Response for interactive message endpoints (buttons, CTA URL, list)."
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API token from your WATI Dashboard > API Settings. Pass as `Authorization: Bearer <token>`."
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}
```