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

# Send template messages

Inspect HTTP status and the business result separately. Even when success is true, recipients can contain errors or requested recipients can be absent. Reconcile returned identifiers with the request before deciding what to retry; acceptance is not delivery confirmation. A timeout, connection loss or 5xx can leave an unknown outcome. Neither broadcast_name nor local_message_id establishes a request-level idempotency guarantee.

- HTTP 200 carries a business result; inspect `success` and `error`. A 200 can report a failed request. A successful result is not a delivery confirmation.
- To know if a message is failed, listen to the **Template 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`, `messagetemplatev3: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.

Each recipient must have a non-empty `phone_number` or `target`. A target may be a phone number, contact ID, or a BSUID when enabled for the workspace. When both are present, a non-whitespace target takes precedence. Select the channel with the top-level `channel` field. An unresolved or unavailable target may be absent from `recipients`; inspect the overall result and use delivery webhooks for the outcome.

For approved-template parameter/media examples, recipient reconciliation and V1 migration, see the [Template Message Payload Guide](https://docs.wati.io/reference/template-message-payload-guide).

# 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": "Templates",
      "description": "Manage and send WhatsApp message templates."
    }
  ],
  "paths": {
    "/api/ext/v3/messageTemplates/send": {
      "post": {
        "tags": [
          "Templates"
        ],
        "summary": "Send template messages",
        "description": "Inspect HTTP status and the business result separately. Even when success is true, recipients can contain errors or requested recipients can be absent. Reconcile returned identifiers with the request before deciding what to retry; acceptance is not delivery confirmation. A timeout, connection loss or 5xx can leave an unknown outcome. Neither broadcast_name nor local_message_id establishes a request-level idempotency guarantee.\n\n- HTTP 200 carries a business result; inspect `success` and `error`. A 200 can report a failed request. A successful result is not a delivery confirmation.\n- To know if a message is failed, listen to the **Template 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`, `messagetemplatev3: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.\n\nEach recipient must have a non-empty `phone_number` or `target`. A target may be a phone number, contact ID, or a BSUID when enabled for the workspace. When both are present, a non-whitespace target takes precedence. Select the channel with the top-level `channel` field. An unresolved or unavailable target may be absent from `recipients`; inspect the overall result and use delivery webhooks for the outcome.\n\nFor approved-template parameter/media examples, recipient reconciliation and V1 migration, see the [Template Message Payload Guide](https://docs.wati.io/reference/template-message-payload-guide).",
        "operationId": "MessageTemplate_SendTemplateMessages",
        "requestBody": {
          "content": {
            "application/json-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/SendTemplateMessagesRequest"
              },
              "example": {
                "channel": "1234567890",
                "template_name": "welcome_template",
                "broadcast_name": "Welcome Campaign",
                "recipients": [
                  {
                    "phone_number": "1234567890",
                    "local_message_id": "local-msg-123",
                    "custom_params": [
                      {
                        "name": "first_name",
                        "value": "John"
                      },
                      {
                        "name": "flow_token",
                        "value": "optional-custom-token"
                      },
                      {
                        "name": "flow_action_data",
                        "value": "{\"screen\":\"WELCOME\",\"data\":{\"user_id\":\"123\"}}"
                      }
                    ]
                  }
                ]
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendTemplateMessagesRequest"
              },
              "example": {
                "channel": "1234567890",
                "template_name": "welcome_template",
                "broadcast_name": "Welcome Campaign",
                "recipients": [
                  {
                    "phone_number": "1234567890",
                    "local_message_id": "local-msg-123",
                    "custom_params": [
                      {
                        "name": "first_name",
                        "value": "John"
                      },
                      {
                        "name": "flow_token",
                        "value": "optional-custom-token"
                      },
                      {
                        "name": "flow_action_data",
                        "value": "{\"screen\":\"WELCOME\",\"data\":{\"user_id\":\"123\"}}"
                      }
                    ]
                  }
                ]
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/SendTemplateMessagesRequest"
              },
              "example": {
                "channel": "1234567890",
                "template_name": "welcome_template",
                "broadcast_name": "Welcome Campaign",
                "recipients": [
                  {
                    "phone_number": "1234567890",
                    "local_message_id": "local-msg-123",
                    "custom_params": [
                      {
                        "name": "first_name",
                        "value": "John"
                      },
                      {
                        "name": "flow_token",
                        "value": "optional-custom-token"
                      },
                      {
                        "name": "flow_action_data",
                        "value": "{\"screen\":\"WELCOME\",\"data\":{\"user_id\":\"123\"}}"
                      }
                    ]
                  }
                ]
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/SendTemplateMessagesRequest"
              },
              "example": {
                "channel": "1234567890",
                "template_name": "welcome_template",
                "broadcast_name": "Welcome Campaign",
                "recipients": [
                  {
                    "phone_number": "1234567890",
                    "local_message_id": "local-msg-123",
                    "custom_params": [
                      {
                        "name": "first_name",
                        "value": "John"
                      },
                      {
                        "name": "flow_token",
                        "value": "optional-custom-token"
                      },
                      {
                        "name": "flow_action_data",
                        "value": "{\"screen\":\"WELCOME\",\"data\":{\"user_id\":\"123\"}}"
                      }
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns the send result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendTemplateMessagesResponse"
                },
                "examples": {
                  "Accepted": {
                    "value": {
                      "success": true,
                      "broadcast_id": "broadcast_123456",
                      "recipients": [
                        {
                          "local_message_id": "local-msg-123",
                          "phone_number": "1234567890",
                          "errors": []
                        }
                      ]
                    }
                  },
                  "Partial recipient failure": {
                    "value": {
                      "success": true,
                      "broadcast_id": "<broadcast-id>",
                      "recipients": [
                        {
                          "local_message_id": "request-1",
                          "target": "<recipient-1>",
                          "errors": []
                        },
                        {
                          "local_message_id": "request-2",
                          "target": "<recipient-2>",
                          "errors": [
                            "Broadcast is not allowed for this contact."
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "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",
                "wati_integration:write",
                "messagetemplatev3: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."
      },
      "SendTemplateMessagesRequest": {
        "required": [
          "broadcast_name",
          "recipients",
          "template_name"
        ],
        "type": "object",
        "properties": {
          "channel": {
            "type": "string",
            "description": "The channel name or number from which the template messages will be sent (null for default channel).",
            "nullable": true
          },
          "template_name": {
            "type": "string",
            "description": "The name of the template to be used for sending messages."
          },
          "broadcast_name": {
            "type": "string",
            "description": "The name of the broadcast to be created."
          },
          "recipients": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TemplateMessageRecipientDto"
            },
            "description": "1–10,000 requested recipients. Account, balance, usage and broadcast limits can further restrict a request. Check success, recipient errors and omitted recipients; the batch limit does not guarantee acceptance or delivery.",
            "minItems": 1,
            "maxItems": 10000
          }
        },
        "additionalProperties": false,
        "description": "Request model for sending template messages."
      },
      "SendTemplateMessagesResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indicates whether the operation was successful."
          },
          "broadcast_id": {
            "type": "string",
            "description": "The ID of the created broadcast.",
            "nullable": true
          },
          "error": {
            "type": "string",
            "description": "An error message, if any.",
            "nullable": true
          },
          "recipients": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TemplateMessageRecipientResultDto"
            },
            "description": "A list of results for each recipient.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Represents the result of sending template messages to recipients."
      },
      "TemplateMessageRecipientDto": {
        "type": "object",
        "properties": {
          "phone_number": {
            "type": "string",
            "description": "Recipient phone number; optional if target is provided.",
            "nullable": true
          },
          "local_message_id": {
            "type": "string",
            "description": "The local message identifier.",
            "nullable": true
          },
          "custom_params": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TemplateParameterDto"
            },
            "description": "A list of custom parameters to be used in the template message.",
            "nullable": true
          },
          "target": {
            "type": "string",
            "nullable": true,
            "description": "Recipient phone number, contact ID, or supported BSUID; optional if phone_number is provided. BSUID support depends on availability for your workspace."
          }
        },
        "additionalProperties": false,
        "description": "Provide a non-empty phone_number or target for each recipient. When both are provided, a non-whitespace target takes precedence.",
        "anyOf": [
          {
            "required": [
              "phone_number"
            ],
            "properties": {
              "phone_number": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          {
            "required": [
              "target"
            ],
            "properties": {
              "target": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        ]
      },
      "TemplateMessageRecipientResultDto": {
        "type": "object",
        "properties": {
          "local_message_id": {
            "type": "string",
            "description": "The local message identifier.",
            "nullable": true
          },
          "phone_number": {
            "type": "string",
            "description": "Recipient phone number, when available; it can be empty for a BSUID-only contact.",
            "nullable": true
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "A list of errors encountered while sending the message, if any.",
            "nullable": true
          },
          "target": {
            "type": "string",
            "nullable": true,
            "description": "Recipient target, when returned."
          }
        },
        "additionalProperties": false,
        "description": "DTO representing the result of sending a template message to a recipient."
      },
      "TemplateParameterDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the template parameter.",
            "nullable": true
          },
          "value": {
            "type": "string",
            "description": "The value of the template parameter.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Represents a parameter used within a message template."
      },
      "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 <token>`."
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}
```