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://api.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://api.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.

Campaign Report

Use a GET request to pull the delivery log for every template message you have sent through the Template API. You get one row per message, so you can aggregate the numbers however your CRM needs them — totals per template, delivery and read rates, failure reasons, or per-contact status.

These are the same records shown in your TailorTalk dashboard on the Campaign page, under the API section.

API Endpoint

https://api.tailortalk.ai/api/v1/campaign_logs

Authentication

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

Query Parameters

Parameter Required Description
template_name ❌ Return only messages sent with this template. Omit it to get every template.
limit ❌ Number of rows per request. Default 200, maximum 500.
start_after ❌ Cursor for the next page. Pass the next_cursor value from your previous response.

Example Requests

GET https://api.tailortalk.ai/api/v1/campaign_logs
GET https://api.tailortalk.ai/api/v1/campaign_logs?template_name=order_update
GET https://api.tailortalk.ai/api/v1/campaign_logs?template_name=diwali_offer&limit=500

Example Response

{
  "logs": [
    {
      "message_id": "wamid.HBgL...",
      "contact_number": "919816923811",
      "template_name": "order_update",
      "status": "read",
      "error": null
    },
    {
      "message_id": "wamid.HBgM...",
      "contact_number": "919816923812",
      "template_name": "diwali_offer",
      "status": "failed",
      "error": "Invalid number"
    }
  ],
  "count": 2,
  "next_cursor": "2026-09-18T12:00:00+00:00"
}
Field Description
message_id The same message_id the Template API returned when you sent the message. Use it to join these rows onto your own records.
contact_number Contact the message was sent to, with country code
template_name WhatsApp template that was sent
status Latest delivery status: sent, delivered, read, replied, or failed
error Reason the message failed. null for messages that did not fail.
count Number of rows in this response
next_cursor Pass this back as start_after to fetch the next page. null when there are no rows.

Pagination

Rows come back newest first. To walk through your full history, send the next_cursor from each response as start_after on the next request, and stop when logs comes back empty.

GET https://api.tailortalk.ai/api/v1/campaign_logs?limit=500
GET https://api.tailortalk.ai/api/v1/campaign_logs?limit=500&start_after=2026-09-18T12:00:00+00:00

Note: Status moves forward only, sent → delivered → read → replied, so a row always shows the furthest point the message reached. A message you just sent may still show sent until WhatsApp delivers its status webhook. Only messages sent through the Template API appear here — dashboard broadcasts and campaigns are excluded.

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://api.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://api.tailortalk.ai/api/v1/get_whatsapp_templates
GET https://api.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