WhatsApp Template API

Developer API

Send approved WhatsApp templates from your own systems with one API call; the conversation then continues in MonoChat.

• WhatsApp
• REST API
• API only

Install from MonoStoreSee it on monochat.ai

Overview

WhatsApp Template API lets your CRM, ERP, e-commerce site or any backend send an approved WhatsApp template message to a customer through MonoChat. One request names the WhatsApp number to send from, the customer’s phone number, the template and its variables.

When the customer replies, the conversation lands in your MonoChat inbox like any other. The app has no screens of its own: everything happens through three API endpoints.

Highlights

• One API call. Send a template by name and language, with header, body, button and carousel variables filled from your data.
• Straight to the chat. Every send returns the conversation’s id and a direct link to it in MonoChat.
• New customers welcome. If the phone number is not a customer yet, the customer is created with the name you send.

Install and set up

1. Connect your WhatsApp Business number to MonoChat and make sure it is verified and has templates approved by Meta.
2. Install WhatsApp Template API from Settings › MonoStore › Apps, or open the install link app.monochat.ai/apps/K6u29LpbwCHBozZ8o. Without a MonoChat account, the link lets you sign up first and installs the app for you.
3. Create an API token under Profile › API Tokens. The token is shown only once, so copy it right away.
4. Call template/list.js to see your approved templates and their variables.
5. Call template/send.js with the customer's number and the variable values to send your first template.

note

• Each message is billed like any template message sent from MonoChat.
• Media URLs must stay reachable until WhatsApp has fetched the file.
• Send to customers who agreed to hear from you: WhatsApp can limit numbers whose messages are blocked or reported.

Screen by screen

WhatsApp Template API has no screen of its own and adds nothing to the left menu. You see it in two places: when you install it, and on your list of installed apps.

Install

Click Install in the MonoStore App Preview drawer. There is nothing to set up inside MonoChat after that, apart from the API token.

Installed Apps

Once installed, the app appears as a card under Settings › MonoStore › Installed Apps, with its version, publisher and description.

Everything else happens through the API: list your templates, send a template and upload media for a header. See API reference and Errors.

Features

List templates

The approved templates of a WhatsApp number, with their language, category, status and variables, so your system knows what it can send.

Send a template

By template name and language, with header, body, button and carousel variables. A missing value stops the send, so nothing half-filled reaches the customer.

Assign to an agent

Give an agent’s email and the conversation is opened on their name.

Media headers

Get short-lived upload credentials, put an image, video or document on MonoChat’s storage and use its URL as the template’s header.

Conversation link

Each send returns the session id, message id and a link that opens the conversation in MonoChat.

Clear errors

A failed call says what went wrong, for example “Channel not found” or “Variable missing”.

Before you start

• Your WhatsApp Business number is connected to MonoChat and verified. See Channels.
• The templates you want to send are approved by Meta. Templates are how you write first, or reach a customer outside the 24-hour window. See Template Messages.
• You have an API token from Profile › API Tokens. See API Tokens.
• You know your tenant slug: the part after /tenants/ in your MonoChat address. In https://app.monochat.ai/tenants/mybusiness the slug is mybusiness.

API reference

The app has no screens of its own. Everything happens through three endpoints, each a POST with a JSON body:

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Endpoint	What it does
template/list.js	Lists the templates of one of your WhatsApp numbers, with their variables.
template/send.js	Sends a template to a customer and returns a link to the conversation.
upload/get-token.js	Gives short-lived upload credentials for a header image, video or document.

Phone numbers are always written with the country code and without +, for example 905334445566. A successful call answers 200 with the endpoint's data under result.

1. List templates

POST /api/<slug>/custom-functions/template-app/api/template/list.js

Lists every template of the given WhatsApp Business number: name, language code, category, components (header, body, footer, buttons), variable types and approval status.

Field	Required	Description
phoneNumber	yes	Your WhatsApp Business number in MonoChat, with country code, without +.
options	no	Paging and filters, for example { "pagination": { "currentPage": 1, "pageItems": 50 } }.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

Response (shortened):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

How to read it:

• name: the system name you send the template with.
• languageCode: the language to send it in.
• category: the WhatsApp category (MARKETING, UTILITY, AUTHENTICATION).
• components: the parts the template is built from.

Component	Content	Description
HEADER	IMAGE, VIDEO, DOCUMENT or text	For media the format is given; variables appear under variables.
BODY	Text with variables	The message body, with placeholders such as {{1}}, {{2}}.
FOOTER	Text	Usually has no variables.
BUTTONS	URL, quick reply…	Button texts and their variables, if any.

The example template above needs one image for the header and two texts for the body (customer name and product name). The footer is fixed ("Teşekkürler") and there are no buttons.

2. Send a template

POST /api/<slug>/custom-functions/template-app/api/template/send.js

Sends an approved template to a customer. If the phone number is not a customer yet, the customer is created; the conversation is opened (or reused) and the template is sent in it.

Field	Required	Description
phoneNumber	yes	The WhatsApp Business number to send from. It must be connected to MonoChat and verified.
templateMessageName	yes	The template's name, exactly as the list returns it.
languageCode	yes	The template's language, as the list returns it (for example tr-TR).
customerPhoneNumber	yes	The customer's WhatsApp number.
variables	when the template has any	The values of the template's variables (see below).
customerFirstName, customerLastName	no	Used when the customer is new to MonoChat.
agentEmailAddress	no	Assigns the conversation to the agent with this email.

Variables. Each item of the variables array has a type and a list of parameters, given in the order of the template's placeholders:

type	parameters
HEADER	The header text variable, or the public URL of the header image, video or document.
BODY	The body's {{1}}, {{2}}, … in order.
BUTTONS	One value for each button that has a variable (for example the dynamic part of a URL button or a coupon code), in button order.
CAROUSEL	Instead of parameters, a cards array with one entry per carousel card, each with its own components.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

A missing value stops the send with Variable missing, so nothing half-filled reaches the customer. FOOTER rarely has variables.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

Response:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

• url: opens the conversation in MonoChat, for people who are signed in and allowed to see it.
• sessionId: the conversation's id.
• messageId: the id of the message in MonoChat. Its delivery and read status show up in the chat like any other message.

Media in templates. WhatsApp downloads header media from the URL you give, so the URL must be valid and publicly reachable. Links that need a login do not work. If you uploaded the file with upload/get-token.js, use the file's URL built from that answer.

3. Upload media for a header

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

When a template's header is an image, video or document, the file needs a public address WhatsApp can download it from. This endpoint gives you short-lived permission to put the file on MonoChat's storage.

Field	Required	Description
fileName	yes	The file name with its extension, for example product.jpg or promo.pdf.

Files are always stored in your workspace's chat-assets folder; older examples that send a key field keep working, the value is not needed.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

The answer tells you where to put the file and gives credentials to do it:

Field	Description
bucket, region, path	Where the file goes.
temporaryCredentials	Upload-only credentials for that one path, valid for 15 minutes.
baseUrl	The public address of the storage. The file's URL is baseUrl + / + path.

Upload the file right away with any S3 client using these credentials, then pass its URL as the HEADER parameter when you send the template. Very large files or formats WhatsApp does not support (it accepts common image, video and PDF formats) fail.

Example: a template with an image header

Say you have an approved template new_product_announcement with an image header and two body variables (customer name and product name), and you want to send it to a customer.

1. List the templates. Call template/list.js with your WhatsApp number and find new_product_announcement. Its components show one IMAGE variable in the header and two TEXT variables in the body.
2. Upload the image. Call upload/get-token.js with { "fileName": "urun.jpg" }, upload the file with the returned credentials and build its URL from baseUrl and path.
3. Send the template. Call template/send.js with the file URL as the HEADER parameter and ["Ayşe", "XYZ Telefon"] as the BODY parameters ({{1}} → Ayşe, {{2}} → XYZ Telefon). If the template had button variables you would add a BUTTONS item the same way.
4. Open the chat. The answer's url opens the conversation; when the customer replies, it continues in your MonoChat inbox.

Errors

A failed call answers with an error status and a message that says what went wrong. Log these messages in your system and show a meaningful message to your users where needed.

Message	Cause
phoneNumber field is required	template/list.js was called without phoneNumber.
phoneNumber, templateMessageName, customerPhoneNumber fields are required	A required field of template/send.js is missing.
Channel not found	The phoneNumber is not a WhatsApp number of your workspace.
Channel is not verified	The WhatsApp number is connected but not verified.
Template message not found	No approved template with that name and language on the number. Check the spelling and languageCode.
Template message is not approved	The template exists but is not approved by Meta.
Variable missing: …	variables does not match the template, for example the template needs two body values and you sent one.
Agent user not found	No agent with the email in agentEmailAddress.
Customer Channel not found	The customer's WhatsApp identity could not be created or found.

HTTP status codes you may see:

• 401 Unauthorized: the Authorization: Bearer <API_TOKEN> header is missing, or the token is wrong or expired. Use a valid token from your account.
• 403 Forbidden: the token has no access to this workspace or app, for example a wrong tenant slug.
• 404 Not Found: the endpoint address is wrong. Check the full path /api/<slug>/custom-functions/template-app/api/....
• 500 Internal Server Error: an unexpected problem in MonoChat or at the WhatsApp provider, or a WhatsApp-side refusal (the number is not on WhatsApp, the customer blocked you, quality or rate limits). Retry later and contact MonoChat support if it persists.

Screenshots

Sending an approved WhatsApp template from a CRM, ERP or e-commerce system with one API call through MonoChatThe list of approved WhatsApp templates with their variablesSending a template to a new number creates the customer automaticallyOne template sent in several languagesTemplates with image, video, document and PDF headers

FAQ

Does WhatsApp Template API have a user interface?

No. It is an API-only app with three endpoints: list templates, send a template and get upload credentials for media headers.

What do I need before I can use it?

A WhatsApp Business number connected to MonoChat and verified, templates approved by Meta, and an API token from Profile › API Tokens.

What happens when the customer replies?

The conversation lands in your MonoChat inbox like any other. Each send also returns a direct link to the conversation, and you can assign it to an agent by email.

Can I send to a number that is not a customer yet?

Yes. If the phone number is not a customer yet, the customer is created with the name you send.

What do template messages cost?

Each message is billed like any template message sent from MonoChat. Meta prices templates by category and the recipient’s country; use the WhatsApp bulk messaging cost calculator to estimate a send.

Related

• Session Link
• Bulk Template Message API
• Template Messages
• MonoStore apps