Campaigns: Template API

Use the Template API to send an approved WhatsApp template message to a single lead programmatically via a POST request. Messages sent via this API are recorded in the chat history, ensuring that agents have full context if the lead responds.

API Endpoint

https://service.tailortalk.ai/api/v1/send_whatsapp_template_message

Authentication

Headers

Key Value
Authorization Agent <token>

You can find the agent_token on the Developer page in your TailorTalk dashboard, under the API Keys tab. Click the eye icon to reveal it, or the copy icon to copy it.

Agent access token

Request Body

Parameter Required Description
lead_contact ✅ Lead contact number
lead_name ❌ Lead name (optional)
template_name ✅ WhatsApp template name
template_params ❌ Values for template variables. Use a list to match by order, or an object to match by name.
website_button_params ❌ List of dynamic URL suffix values for URL buttons that have {{1}} in their URL. Values are matched in order of button appearance.
copy_code_button_params ❌ Coupon code string for the Copy Code button.
header_media_url ❌ Dynamic media URL for template header (image, document, video). Supported for media templates.
header_media_name ❌ Explicit filename for template header document. Falls back to name from URL if not provided.
lock_lead ❌ If true, the lead will be automatically locked when they reply to this message. Default is false.

Example Request Body (Ordered Variables)

{
  "lead_contact": "9816923811",
  "lead_name": "Shiva",
  "template_name": "order_update",
  "template_params": ["OD1234", "Delhi"]
}

Example Request Body (Named Variables)

{
  "lead_contact": "9816923811",
  "lead_name": "Shiva",
  "template_name": "order_update",
  "template_params": {
    "order_id": "OD1234",
    "city": "Delhi"
  }
}

Example Request Body (With Button Parameters)

If your template has dynamic URL buttons and/or a Copy Code button:

{
  "lead_contact": "9816923811",
  "lead_name": "Shiva",
  "template_name": "promo_template",
  "template_params": {
    "name": "Shiva",
    "order_id": "OD1234"
  },
  "website_button_params": ["shiva123", "order/OD1234"],
  "copy_code_button_params": "SAVE20"
}

Note: website_button_params values are appended to the dynamic URL in order. For example, if your template has a button URL https://example.com/track/{{1}} and you pass ["OD1234"], the final URL becomes https://example.com/track/OD1234. Static URL buttons (without {{1}}) do not need any parameters.

Example Request Body (With Header Media)

If your template has a media header (Image or Document):

{
  "lead_contact": "9816923811",
  "template_name": "event_invite",
  "template_params": ["Annual Gala", "March 25th"],
  "header_media_url": "https://example.com/invitation_card.jpg",
  "header_media_name": "invitation.jpg"
}

Note: header_media_name is especially useful for Document templates where you want to specify the filename that the user sees when they download the document. If not provided, TailorTalk will try to extract the name from the URL.

Example Request Body (With Lock Lead)

If you want the lead to be automatically locked (preventing the AI agent from responding) when they reply:

{
  "lead_contact": "9816923811",
  "lead_name": "Shiva",
  "template_name": "order_update",
  "template_params": ["OD1234", "Delhi"],
  "lock_lead": true
}

Note: When lock_lead is set to true, the lead will be automatically locked as soon as they reply to the template message. A locked lead will not receive AI-generated responses until manually unlocked. This is useful when you want a human agent to handle the conversation.

Response

On success, the API returns the ID of the sent message which can be used to track its delivery status:

{
  "message": "Message sent successfully.",
  "message_id": "wamid.HBgL..."
}

Check Message Status

You can check the delivery status of a message sent via the Template API using a GET request. The status information is retained for up to 14 days.

API Endpoint

https://service.tailortalk.ai/api/v1/message_status?message_id={message_id}

Authentication

Requires the same Authorization: Agent <token> header as the Template API.

Query Parameters

Parameter Required Description
message_id ✅ The message_id returned by the Template API

Example Response

{
  "message_id": "wamid.HBgL...",
  "status": "delivered"
}

Note: The status can be one of: sent, delivered, read, or failed. If the message ID is invalid or older than 14 days, the API will return a 400 Bad Request error.

Get WhatsApp Templates

Use a GET request to list your WhatsApp templates with their approval status and type (Meta category). Use it to confirm a template is approved before sending it with the Template API.

API Endpoint

https://service.tailortalk.ai/api/v1/get_whatsapp_templates

Authentication

Requires the same Authorization: Agent <token> header as the Template API.

Query Parameters

Parameter Required Description
template_name ❌ Name of a single template to fetch. Omit it to fetch all templates.

Example Requests

GET https://service.tailortalk.ai/api/v1/get_whatsapp_templates
GET https://service.tailortalk.ai/api/v1/get_whatsapp_templates?template_name=order_update

Example Response

{
  "templates": [
    {
      "template_name": "order_update",
      "template_status": "APPROVED",
      "template_type": "UTILITY",
      "language": "en"
    },
    {
      "template_name": "diwali_offer",
      "template_status": "PENDING",
      "template_type": "MARKETING",
      "language": "en"
    }
  ],
  "count": 2
}
Field Description
template_name Name of the template, as used in the Template API
template_status Approval status: APPROVED, PENDING, REJECTED, PAUSED, or DISABLED
template_type Meta category of the template: MARKETING, UTILITY, or AUTHENTICATION
language Language code of the template, e.g. en, en_US

Note: Only templates with template_status: APPROVED can be sent. If template_name does not exist, the API returns Template <name> not found, and if WhatsApp is not connected for the agent it returns WhatsApp is not connected for this agent. Up to 100 templates are returned when template_name is omitted.

Notes

  • The template must be Approved in WhatsApp before it can be used.
  • Messages sent via this API will be visible in the lead's chat history.
  • If the lead responds, the agent will respond based on the template message context.
  • WhatsApp conversation charges apply.
XLinkedIn