WhatsApp Templates

Use the WhatsApp Templates API for proactive messages that must use Meta-approved templates: order confirmations, appointment reminders, payment updates, account notices, and other transactional workflows. All endpoints use the M2M base URL:

https://platform-api.visitoai.com/m2m/v1

Requirements

A connected, active WhatsApp channel using the Meta provider.
The channel must have Meta wabaId, phoneNumberId, and access token details configured in Visito.
An M2M credential with the template scopes you need.
Idempotency-Key on template send requests.

Use GET /m2m/v1/channels to find the channelId for the WhatsApp number you want to send from.

List Templates

GET /m2m/v1/whatsapp-templates/{channelId} HTTP/1.1
Host: platform-api.visitoai.com
Authorization: Bearer visito_m2m_...
Accept: application/json

Requires the whatsapp_templates:read scope.

{
  "templates": [
    {
      "id": "1234567890",
      "name": "order_confirmed",
      "status": "APPROVED",
      "language": "en_US",
      "category": "UTILITY",
      "components": [
        {
          "type": "BODY",
          "text": "Hi {{1}}, your order is confirmed."
        }
      ]
    }
  ]
}

Create a Template

POST /m2m/v1/whatsapp-templates/{channelId} HTTP/1.1
Host: platform-api.visitoai.com
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requires whatsapp_templates:write. template.name must use lowercase letters, numbers, and underscores. template.category must be UTILITY, MARKETING, or AUTHENTICATION.

{
  "template": {
    "name": "order_confirmed",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order is confirmed.",
        "example": {
          "body_text": [["Sofia"]]
        }
      }
    ]
  }
}

{
  "template": {
    "id": "1234567890",
    "name": "order_confirmed",
    "status": "PENDING",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order is confirmed."
      }
    ]
  }
}

Templates must be approved by Meta before they can be sent.

Send a Template

POST /m2m/v1/whatsapp-templates/{channelId}/send HTTP/1.1
Host: platform-api.visitoai.com
Authorization: Bearer visito_m2m_...
Idempotency-Key: order-123-confirmation
Content-Type: application/json

Requires whatsapp_templates:send.

{
  "to": "+525512345678",
  "template": {
    "name": "order_confirmed",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Sofia"
          }
        ]
      }
    ]
  }
}

If accepted, Visito queues the send and returns 202 Accepted.

{
  "accepted": true,
  "conversationId": "conv_...",
  "conversationKey": "tenant_...:whatsapp:525512345678:phone_number_id",
  "replyId": "reply_...",
  "requestEventId": "event_...",
  "correlationId": "corr_...",
  "status": "queued",
  "acceptedAt": "2026-07-12T00:00:00.000Z"
}

Template sends are asynchronous. The API response confirms Visito accepted and queued the outbound work; it does not return the raw Meta send response.

Send Rules

The template must exist for the requested language.
The template status must be APPROVED.
REJECTED, PENDING, or in-review templates cannot be sent.
to can include formatting such as +, spaces, or punctuation; Visito normalizes it to WhatsApp digits.
Reusing the same Idempotency-Key for the same recipient conversation returns the original accepted send instead of creating a duplicate.
Limits are calculated per workspace and WhatsApp channel over a rolling 24-hour window. UTILITY templates allow 2,000 sends. MARKETING, AUTHENTICATION, and older unclassified sends share a separate limit of 100.
When the applicable category limit is reached, Visito returns 429 with the limit and retry details.

Common Errors

Code	Meaning
`WHATSAPP_TEMPLATES_CHANNEL_NOT_FOUND`	The channel does not belong to the authenticated tenant.
`WHATSAPP_TEMPLATES_UNSUPPORTED_CHANNEL`	The channel is not a WhatsApp Meta channel.
`WHATSAPP_TEMPLATES_CHANNEL_NOT_READY`	The channel is missing Meta connection details.
`WHATSAPP_TEMPLATES_TEMPLATE_NOT_FOUND`	No template exists with that name and language.
`WHATSAPP_TEMPLATES_TEMPLATE_NOT_APPROVED`	The template exists but is not approved by Meta.
`WHATSAPP_TEMPLATE_SEND_LIMIT_24H_REACHED`	The channel reached the applicable rolling 24-hour category limit.

Rate-limit responses include the wait time in seconds:

{
  "error": {
    "code": "WHATSAPP_TEMPLATE_SEND_LIMIT_24H_REACHED",
    "message": "WhatsApp template send limit reached for this channel.",
    "details": {
      "limit": 2000,
      "retryAfterSeconds": 3600
    }
  }
}

Use details.limit as the applicable limit for that request. Retry the exact same send body with the same Idempotency-Key after the wait period. A replay returns the identifiers from the original accepted operation.

Build With Visito

AI Coding Assistants

Requirements

List Templates

Create a Template

Send a Template

Send Rules

Common Errors

​Requirements

​List Templates

​Create a Template

​Send a Template

​Send Rules

​Common Errors

Requirements

List Templates

Create a Template

Send a Template

Send Rules

Common Errors