📋 Before You Start

Make sure you have the following elements to carry out your integrations successfully:

Valid UUID Token: It is your main credential. It automatically identifies your company (so you do not need to send the companyId in the JSON).
Channel Number: You must have on hand the active phone number, always including the country code (e.g. +5491112345678).
HTTP Client: Use tools for API testing such as Postman, Insomnia or directly the terminal with curl.

⚙️ Configuration Steps

Step 1: Authorization Header

Every request you make to the API strictly requires the following headers. Without them, the server will reject the request with a 401 Unauthorized error.

HTTP

Authorization: Bearer <your-token-uuid>
Content-Type: application/json

💡 Tip: Since the token already automatically identifies your company in our database, never include the companyId field in the request body; the API resolves it internally in a secure way.

Step 2: Create a Template (POST)

Use the POST method to register and submit a new template for review in Meta through the Atom flow.

Required Fields:

Field	Type	Description
`channelNumber`	string	Channel phone number (e.g. +5491112345678).
`platform`	string	Must always be the value `"whatsapp"`.
`language`	string	Official language code (e.g. `"es"`, `"en_US"`, `"pt_BR"`).
`category`	string	Content type: `"MARKETING"`, `"UTILITY"` or `"AUTHENTICATION"`.
`components`	array	The array with the blocks that make up the message (text, buttons, etc.).
`groupIds`	string[]	IDs of groups authorized to use it. (Use `["ALL"]` for all).
`groupNames`	string[]	Names of groups that match the IDs (e.g. `["ALL"]`).

Optional Fields:

Field	Type	Default	Description
`name`	string	—	Unique template name. Always use `snake_case` format.
`makeUnique`	boolean	`false`	If you send `true`, adds a random suffix to avoid name collisions.

Example A — Simple Template (Text Header + Body)

BASH

curl -X POST https://us-central1-atomchat-io.cloudfunctions.net/api/webhook/whatsapp/templates/api \
  -H "Authorization: Bearer <your-token-uuid>" \
  -H "Content-Type: application/json" \
  -d '{
      "channelNumber": "+5491112345678",
      "platform": "whatsapp",
      "language": "es",
      "category": "UTILITY",
      "name": "bienvenida_simple",
      "groupIds": ["ALL"],
      "groupNames": ["ALL"],
      "components": [
        { "type": "HEADER", "format": "TEXT", "text": "Welcome" },
        { "type": "BODY", "text": "Thank you for contacting us. We will assist you shortly." }
      ]
    }'

Example B — Template with Variables and Quick Reply Buttons (Note: Use the markers {{1}}, {{2}} for dynamic values. Including the example object with sample values is mandatory, as Meta requires it for review).

BASH

curl -X POST https://us-central1-atomchat-io.cloudfunctions.net/api/webhook/whatsapp/templates/api \
  -H "Authorization: Bearer <your-token-uuid>" \
  -H "Content-Type: application/json" \
  -d '{
      "channelNumber": "+5491112345678",
      "platform": "whatsapp",
      "language": "es",
      "category": "UTILITY",
      "name": "pedido_con_params",
      "groupIds": ["ALL"],
      "groupNames": ["ALL"],
      "components": [
        { "type": "HEADER", "format": "TEXT", "text": "Order Request" },
        {
          "type": "BODY",
          "text": "Dear {{1}}, thank you for your interest in the {{2}} model.",
          "example": { "body_text": [["Customer_Name", "Vehicle_Model"]] }
        },
        { "type": "FOOTER", "text": "We are here to serve you." },
        {
          "type": "BUTTONS",
          "buttons": [
            { "type": "QUICK_REPLY", "text": "Confirm order" },
            { "type": "QUICK_REPLY", "text": "Modify order" }
          ]
        }
      ]
    }'

Step 3: Update an Existing Template (PATCH)

Use this method to update the internal metadata of a template in Atom.

⚠️ Important: The actual WhatsApp content (components, text, buttons and language) CANNOT be modified via API once the template has been created/approved.

Available Fields (At least one is required in the body):

Field	Type	Description
`description`	string	Internal display name for the template within Atom.
`groupIds`	string[]	IDs of groups authorized to use this template.
`groupNames`	string	Group names corresponding to the `groupIds`.
`active`	boolean	`true` to enable its use, `false` to disable it.

Example PATCH request:

BASH

curl -X PATCH "https://us-central1-atomchat-io.cloudfunctions.net/api/webhook/whatsapp/templates/api?channelNumber=+5491112345678&page=1" \
  -H "Authorization: Bearer <your-token-uuid>" \
  -H "Content-Type: application/json" \
  -d '{
      "description": "Summer promo 2025",
      "active": false
    }'

Step 4: List Templates (GET)

Retrieve all templates associated with your channel. This endpoint supports pagination and sorting to facilitate handling large volumes of data.

Query Parameters:

Parameter	Type	Required	Default	Description
`channelNumber`	string	Yes	—	Exact phone number to filter.
`page`	number	No	`1`	Page number to query.
`size`	number	No	`10`	Number of results per page.
`sort`	string	No	`"asc"`	Sort direction: `"asc"` or `"desc"`.

Example GET request:

BASH

curl -X GET "https://us-central1-atomchat-io.cloudfunctions.net/api/webhook/whatsapp/templates/api?channelNumber=+5491112345678&page=1&size=20&sort=desc" \
  -H "Authorization: Bearer <your-token-uuid>"

💡 Recommendations and Best Practices

Clean Naming: Always use snake_case format (e.g. welcome_new_customer) in your template names to avoid syntax errors in Meta's validation.
Use of makeUnique: If you experience "duplicate name" errors when trying to replace a template you just deleted, send "makeUnique": true. The API will automatically add a numeric suffix to avoid collisions.
Header Formats: Remember that in addition to "format": "TEXT", WhatsApp headers support multimedia content using "format": "IMAGE", "VIDEO", or "DOCUMENT".

⚠️ Common Troubleshooting

If your API calls fail, review these critical points:

Error 401 (Unauthorized): The UUID token is incorrect, expired, or the header does not have exactly the format Bearer <your-token>.
Error 404 (Channel not found): The channelNumber sent is not registered or is not active within your Atom account. Make sure to include the country code without the + symbol if the API throws you URL format errors, or exactly as it is registered on the platform.
Template stuck in PENDING state: Remember that review is an external audit process performed by Meta (WhatsApp). It can take anywhere from a few seconds to 24 hours to be approved.

Automate your communication at scale! 🚀

Integrating template management through our API allows you to scale your operations, synchronize your internal systems with Atom, and keep your WhatsApp campaigns running seamlessly and without manual intervention. ✅

How to create and manage WhatsApp templates using the API

📋 Before You Start

⚙️ Configuration Steps

Step 1: Authorization Header

Step 2: Create a Template (POST)

Step 3: Update an Existing Template (PATCH)

Step 4: List Templates (GET)

💡 Recommendations and Best Practices

⚠️ Common Troubleshooting