--- updatedAt: 2026-10-30T08:42:27.000Z agentTools: projectIndex: https://docs.wati.io/llms.txt --- # Send a text message to an active conversation is_bot defaults to true. On Instagram, false is for a genuine human-agent reply and uses its existing granted reply deadline; without one, the normal 24-hour window applies. It does not authorize automated messages outside their window or reopen an expired session. The field is ignored on WhatsApp. Supported channels for this REST operation: WhatsApp and Instagram. Use a conversation ID from a relevant conversation response for that workspace and channel; do not substitute a contact ID. A target accepted by another endpoint does not imply this operation supports that channel. The customer-service/reply window and channel permissions must still allow the send. - 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`, `conversationsv3:write`, `wati_integration: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 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": "Conversations", "description": "Send messages (text, file, interactive), manage conversation status and operator assignment." } ], "paths": { "/api/ext/v3/conversations/messages/text": { "post": { "tags": [ "Conversations" ], "summary": "Send a text message to an active conversation", "description": "is_bot defaults to true. On Instagram, false is for a genuine human-agent reply and uses its existing granted reply deadline; without one, the normal 24-hour window applies. It does not authorize automated messages outside their window or reopen an expired session. The field is ignored on WhatsApp.\n\nSupported channels for this REST operation: WhatsApp and Instagram. Use a conversation ID from a relevant conversation response for that workspace and channel; do not substitute a contact ID. A target accepted by another endpoint does not imply this operation supports that channel. The customer-service/reply window and channel permissions must still allow the send.\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`, `conversationsv3:write`, `wati_integration: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": "Conversations_SendText", "requestBody": { "content": { "application/json-patch+json": { "schema": { "$ref": "#/components/schemas/SendTextRequest" }, "example": { "target": "123456789:1415552671", "text": "Hello world", "is_bot": true } }, "application/json": { "schema": { "$ref": "#/components/schemas/SendTextRequest" }, "example": { "target": "123456789:1415552671", "text": "Hello world", "is_bot": true } }, "text/json": { "schema": { "$ref": "#/components/schemas/SendTextRequest" }, "example": { "target": "123456789:1415552671", "text": "Hello world", "is_bot": true } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/SendTextRequest" }, "example": { "target": "123456789:1415552671", "text": "Hello world", "is_bot": true } } } }, "responses": { "200": { "description": "Returns the sent message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendTextResponse" }, "example": { "message": { "text": "Hello, this is a sample message!", "type": "text", "timestamp": "2026-07-14T16:15:38.3992429Z", "owner": true, "status": "delivered", "avatar_url": "https://example.com/avatar.png", "assigned_id": "6858f59a3374901cc1c8223f", "operator_name": "John Doe", "bot_type": "regular", "local_message_id": "88aed3c93a050b3c53978463", "id": "507f1f77bcf86cd799439011", "created": "2026-07-14T16:15:38.3992421Z", "conversation_id": "685bd235e6119686e693a093", "ticket_id": "68aed3c93a050b3c53978463", "event_type": "message" } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestResponse" } } } }, "401": { "description": "The request is unauthorized." }, "403": { "description": "The request is forbidden. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenRequestResponse" } } } }, "429": { "description": "Too many requests. Either the rate limit has been exceeded or usage limits have been reached." }, "500": { "description": "Unexpected error occurred. Please try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } } }, "x-wati-permissions": { "scopeRequirementGroups": [ { "anyOf": [ "api", "conversationsv3:write", "wati_integration:write" ] } ], "groupOperator": "allOf", "appliesTo": [ "ApiAccessToken", "OIDC" ], "legacyJwtScopeCheck": "skipped", "apiAccessTokenHierarchy": "configured-by-identity-provider", "oidcFallbackWhenNoEndpointScope": null, "sourceCommit": "03c6d4bc1590408c569e65602f969c6a596672e3" } } } }, "components": { "schemas": { "ForbiddenRequestResponse": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "integer", "description": "The error code associated with the error.", "format": "int32" }, "message": { "type": "string", "description": "The descriptive error message explaining what went wrong.", "nullable": true }, "timestamp": { "type": "string", "description": "The timestamp indicating when the error was recorded.", "format": "date-time" } }, "additionalProperties": false, "description": "Represents the result of a forbidden request, containing error details." }, "InvalidRequestResponse": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "integer", "description": "The error code associated with the error.", "format": "int32" }, "message": { "type": "string", "description": "The descriptive error message explaining what went wrong.", "nullable": true }, "timestamp": { "type": "string", "description": "The timestamp indicating when the error was recorded.", "format": "date-time" } }, "additionalProperties": false, "description": "Represents the result of a bad request, containing error details." }, "MessageDto": { "type": "object", "properties": { "text": { "type": "string", "description": "The text content of the message.", "nullable": true }, "type": { "type": "string", "description": "The message type.", "nullable": true }, "timestamp": { "type": "string", "description": "The timestamp string of the message.", "nullable": true }, "owner": { "type": "boolean", "description": "Indicates whether the message was sent by the owner." }, "status": { "type": "string", "description": "The current status of the message.", "nullable": true }, "avatar_url": { "type": "string", "description": "The avatar URL of the sender.", "nullable": true }, "assigned_id": { "type": "string", "description": "The assigned operator ID.", "nullable": true }, "operator_name": { "type": "string", "description": "The operator's display name.", "nullable": true }, "failed_detail": { "type": "string", "description": "Details of a failed message delivery, if any.", "nullable": true }, "bot_type": { "type": "string", "description": "The type of bot, if applicable.", "nullable": true }, "id": { "type": "string", "description": "The unique identifier of the conversation event.", "nullable": true }, "created": { "type": "string", "description": "The creation timestamp of the event.", "format": "date-time" }, "conversation_id": { "type": "string", "description": "The associated conversation identifier.", "nullable": true }, "ticket_id": { "type": "string", "description": "The associated ticket identifier.", "nullable": true }, "event_type": { "type": "string", "description": "The type of event (e.g., message, ticket, broadcast).", "nullable": true }, "local_message_id": { "type": "string", "nullable": true, "description": "The local identifier of the message, if available." } }, "additionalProperties": false, "description": "Represents a message event within a conversation." }, "SendTextRequest": { "required": [ "target", "text" ], "type": "object", "properties": { "target": { "type": "string", "description": "The target conversation in the following formats:\n* **`ConversationId`**: The unique ID of a conversation.\n* **`PhoneNumber`**: The recipient's phone number (e.g., `14155552671`).\n* **`Channel:PhoneNumber`**: A combination of the channel (name or phone number) and the recipient's phone number (e.g., `MyChannel:1415552671`, `123456789:1415552671`)." }, "text": { "type": "string", "description": "Message content." }, "is_bot": { "type": "boolean", "default": true, "description": "Whether the Instagram reply is automated. Defaults to true. For a genuine human-agent reply, false uses the human-agent reply deadline if one is available; otherwise the normal 24-hour window still applies. It does not grant a longer window or bypass an expired session. Ignored for WhatsApp." } }, "additionalProperties": false, "description": "Request model for sending a text message." }, "SendTextResponse": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/MessageDto" } }, "additionalProperties": false, "description": "Response model for sending a text message." }, "UnexpectedErrorResponse": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "integer", "description": "The error code associated with the error.", "format": "int32" }, "message": { "type": "string", "description": "The descriptive error message explaining what went wrong.", "nullable": true }, "timestamp": { "type": "string", "description": "The timestamp indicating when the error was recorded.", "format": "date-time" } }, "additionalProperties": false, "description": "Represents an unexpected error." } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API token from your WATI Dashboard > API Settings. Pass as `Authorization: Bearer `." } } }, "security": [ { "BearerAuth": [] } ] } ```