1. Whatsapp API
Hatif
  • Account API
    • Service Login
      POST
  • Channels API
    • Get Channels
      GET
  • Whatsapp API
    • Send Text
      POST
    • Send Template
      POST
  • Contact
    • Set Property Value on Contact
      PUT
    • Search Contacts [Complex]
      POST
    • Delete Property Value on Contact
      DELETE
    • Create Contact
      POST
    • Update Contact
      PUT
    • Get Contacts
      GET
    • Get Contact By Id
      GET
    • Delete Contact
      DELETE
    • Create Bulk Contacts vCards
      POST
    • Create Contact
      POST
    • Get Contacts Search
      POST
    • Contacts History
      GET
  • Contact Properties
    • List Contact Properties
      GET
    • Delete Contact Property
      DELETE
    • Update Contact Property
      PUT
    • Create Contact Property
      POST
    • Contact Properties Statistics
      GET
  • Support API
    • Upload Audio File
      POST
  • Outbound IVR API
    • Create Outbound IVR
      POST
  • Workspace API
    • Get Workspace Users
  • Conversations API
    • Get Conversation Timeline
    • List Conversations
    • Create Conversation
    • Assign Conversation
    • Get Conversation
  • Tags API
    • Create Tag
    • Delete Tag
    • Update Tag
    • List Tags
  • Call Webhook
  • WhatsApp Message Webhook
  • Schemas
    • Call Webhook
    • WhatsApp Message Webhook
    • ConversationDto
    • CreateTagDto
    • ChannelConversationDto
    • UpdateTagDto
    • TagDto
    • ConversationTimelineDto
    • PagedResultOfTagDto
    • AiSummaryDto
    • ReplyInfoDto
    • InternalThreadDto
    • LocationMessageDto
    • AssignationInfoDto
    • PagedResultOfConversationDto
    • PagedResultOfConversationTimelineDto
  1. Whatsapp API

Send Template

POST
/v1/whatsapp/service-account/sendTemplate
Send a WhatsApp template message to a recipient using a pre-approved template.
Templates are messages pre-registered and approved by Meta. They can include dynamic variables in the header, body, and buttons that you fill in at send time using the Parameters array.

Parameters Array#

Each entry in Parameters targets a specific component of the template. The Type field determines which component you're filling:
TypePurpose
HeaderFills the template header — can be text, image, document, or video
BodyFills {{1}}, {{2}}, etc. placeholders in the message body
ButtonsFills dynamic variables in URL or quick reply buttons

Body Parameters#

Body variables are positional — the order of items in Values maps to {{1}}, {{2}}, {{3}}, etc.
{
  "Type": "Body",
  "Values": [
    { "Type": "text", "Text": "value for {{1}}" },
    { "Type": "text", "Text": "value for {{2}}" }
  ]
}

Header Parameters#

If the template has a media header (image, video, or document), you can provide it explicitly. If you omit the header parameter, the system will auto-populate it from the template's example media when
available.
Image header:
{
  "Type": "Header",
  "Values": [
    { "Type": "image", "ImageUrl": "https://example.com/image.jpg" }
  ]
}
Document header:
{
  "Type": "Header",
  "Values": [
    {
      "Type": "document",
      "DocumentUrl": "https://example.com/file.pdf",
      "DocumentFilename": "Invoice.pdf"
    }
  ]
}
Video header:
{
  "Type": "Header",
  "Values": [
    { "Type": "video", "VideoUrl": "https://example.com/video.mp4" }
  ]
}
Text header:
{
  "Type": "Header",
  "Values": [
    { "Type": "text", "Text": "Your Order Update" }
  ]
}

Button Parameters#

There are two critical rules:

Rule 1: Each button is a separate entry#

Unlike body parameters where all variables go into one Values array, each button must be its own separate object in the Parameters array.

Rule 2: SubType and Index are required#

Every button entry must include:
SubType — the button type: "url" or "quick_reply"
Index — the button position: "0" for the first button, "1" for the second, "2" for the third

URL Buttons#

URL button templates define a base URL with a dynamic suffix, e.g. https://example.com/orders/{{1}}. You only provide the dynamic part, not the full URL.
{
  "Type": "Buttons",
  "SubType": "url",
  "Index": "0",
  "Values": [
    { "Type": "text", "Text": "ORD-5123" }
  ]
}
This would produce a button linking to https://example.com/orders/ORD-5123.

Quick Reply Buttons#

Quick reply button values define the payload sent back to your webhook when the customer taps the button. This is not the button label — the label is defined in the template itself.
{
  "Type": "Buttons",
  "SubType": "quick_reply",
  "Index": "0",
  "Values": [
    { "Type": "text", "Text": "confirm_order_123" }
  ]
}

Static buttons don't need parameters#

If a button has no dynamic variable (e.g. a fixed phone number button or a URL with no {{1}}), you do not need to include it in Parameters. Only buttons with dynamic content require parameter
entries.

Examples#

Check the request examples for different types of templates.

Request

Authorization
Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
or
Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200Success
application/json
Bodyapplication/json

Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location 'https://api.voxa.sa/v1/whatsapp/service-account/sendTemplate' \
--header 'Authorization: Bearer <token>' \
--header 'content-type: application/json' \
--data '{
    "ChannelId": "3a197b.....",
    "TemplateName": "order_confirmation1",
    "Language": "en",
    "ToNumber": "9665...",
    "Parameters": [
        {
            "Type": "Body",
            "Values": [
                {
                    "Type": "text",
                    "Text": "Variable 1"
                },
                {
                    "Type": "text",
                    "Text": "Variable 1"
                },
                {
                    "Type": "text",
                    "Text": "Variable 1"
                }
            ]
        }
    ]
}'
Response Response Example
{
    "contactId": "3a18a7e6-48bf-e5b8-4935-867e4b6c6c02",
    "status": "accepted",
    "message": "Template message sent successfully",
    "conversationEventId": "3a1e1287-9c7e-84fc-6eac-c530a49732ea"
}
Modified at 2026-02-25 22:44:58
Previous
Send Text
Next
Set Property Value on Contact
Built with