POST /v1/messages/bulk

Schedule a bulk template broadcast to many recipients

curl --request POST \
  --url https://api.keebai.com/v1/messages/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "template_name": "welcome_v2",
  "language": "es",
  "recipients": [
    {
      "to": "+5491155555555",
      "variables": {
        "nombre": "Juan"
      },
      "meta_data": {}
    }
  ],
  "channel_id": "665f1a2b3c4d5e6f70819234",
  "phone_number_id": "100000000000001",
  "campaign_name": "Onboarding marzo 2026"
}
'

import requests

url = "https://api.keebai.com/v1/messages/bulk"

payload = {
    "template_name": "welcome_v2",
    "language": "es",
    "recipients": [
        {
            "to": "+5491155555555",
            "variables": { "nombre": "Juan" },
            "meta_data": {}
        }
    ],
    "channel_id": "665f1a2b3c4d5e6f70819234",
    "phone_number_id": "100000000000001",
    "campaign_name": "Onboarding marzo 2026"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    template_name: 'welcome_v2',
    language: 'es',
    recipients: [{to: '+5491155555555', variables: {nombre: 'Juan'}, meta_data: {}}],
    channel_id: '665f1a2b3c4d5e6f70819234',
    phone_number_id: '100000000000001',
    campaign_name: 'Onboarding marzo 2026'
  })
};

fetch('https://api.keebai.com/v1/messages/bulk', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.keebai.com/v1/messages/bulk",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'template_name' => 'welcome_v2',
    'language' => 'es',
    'recipients' => [
        [
                'to' => '+5491155555555',
                'variables' => [
                                'nombre' => 'Juan'
                ],
                'meta_data' => [
                                
                ]
        ]
    ],
    'channel_id' => '665f1a2b3c4d5e6f70819234',
    'phone_number_id' => '100000000000001',
    'campaign_name' => 'Onboarding marzo 2026'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.keebai.com/v1/messages/bulk"

	payload := strings.NewReader("{\n  \"template_name\": \"welcome_v2\",\n  \"language\": \"es\",\n  \"recipients\": [\n    {\n      \"to\": \"+5491155555555\",\n      \"variables\": {\n        \"nombre\": \"Juan\"\n      },\n      \"meta_data\": {}\n    }\n  ],\n  \"channel_id\": \"665f1a2b3c4d5e6f70819234\",\n  \"phone_number_id\": \"100000000000001\",\n  \"campaign_name\": \"Onboarding marzo 2026\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.keebai.com/v1/messages/bulk")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"template_name\": \"welcome_v2\",\n  \"language\": \"es\",\n  \"recipients\": [\n    {\n      \"to\": \"+5491155555555\",\n      \"variables\": {\n        \"nombre\": \"Juan\"\n      },\n      \"meta_data\": {}\n    }\n  ],\n  \"channel_id\": \"665f1a2b3c4d5e6f70819234\",\n  \"phone_number_id\": \"100000000000001\",\n  \"campaign_name\": \"Onboarding marzo 2026\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.keebai.com/v1/messages/bulk")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"template_name\": \"welcome_v2\",\n  \"language\": \"es\",\n  \"recipients\": [\n    {\n      \"to\": \"+5491155555555\",\n      \"variables\": {\n        \"nombre\": \"Juan\"\n      },\n      \"meta_data\": {}\n    }\n  ],\n  \"channel_id\": \"665f1a2b3c4d5e6f70819234\",\n  \"phone_number_id\": \"100000000000001\",\n  \"campaign_name\": \"Onboarding marzo 2026\"\n}"

response = http.request(request)
puts response.read_body

{
  "broadcast_id": "<string>",
  "status": "scheduled",
  "total_recipients": 123,
  "scheduled_at": "<string>"
}

POST

messages

bulk

Schedule a bulk template broadcast to many recipients

curl --request POST \
  --url https://api.keebai.com/v1/messages/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "template_name": "welcome_v2",
  "language": "es",
  "recipients": [
    {
      "to": "+5491155555555",
      "variables": {
        "nombre": "Juan"
      },
      "meta_data": {}
    }
  ],
  "channel_id": "665f1a2b3c4d5e6f70819234",
  "phone_number_id": "100000000000001",
  "campaign_name": "Onboarding marzo 2026"
}
'

import requests

url = "https://api.keebai.com/v1/messages/bulk"

payload = {
    "template_name": "welcome_v2",
    "language": "es",
    "recipients": [
        {
            "to": "+5491155555555",
            "variables": { "nombre": "Juan" },
            "meta_data": {}
        }
    ],
    "channel_id": "665f1a2b3c4d5e6f70819234",
    "phone_number_id": "100000000000001",
    "campaign_name": "Onboarding marzo 2026"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    template_name: 'welcome_v2',
    language: 'es',
    recipients: [{to: '+5491155555555', variables: {nombre: 'Juan'}, meta_data: {}}],
    channel_id: '665f1a2b3c4d5e6f70819234',
    phone_number_id: '100000000000001',
    campaign_name: 'Onboarding marzo 2026'
  })
};

fetch('https://api.keebai.com/v1/messages/bulk', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.keebai.com/v1/messages/bulk",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'template_name' => 'welcome_v2',
    'language' => 'es',
    'recipients' => [
        [
                'to' => '+5491155555555',
                'variables' => [
                                'nombre' => 'Juan'
                ],
                'meta_data' => [
                                
                ]
        ]
    ],
    'channel_id' => '665f1a2b3c4d5e6f70819234',
    'phone_number_id' => '100000000000001',
    'campaign_name' => 'Onboarding marzo 2026'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.keebai.com/v1/messages/bulk"

	payload := strings.NewReader("{\n  \"template_name\": \"welcome_v2\",\n  \"language\": \"es\",\n  \"recipients\": [\n    {\n      \"to\": \"+5491155555555\",\n      \"variables\": {\n        \"nombre\": \"Juan\"\n      },\n      \"meta_data\": {}\n    }\n  ],\n  \"channel_id\": \"665f1a2b3c4d5e6f70819234\",\n  \"phone_number_id\": \"100000000000001\",\n  \"campaign_name\": \"Onboarding marzo 2026\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.keebai.com/v1/messages/bulk")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"template_name\": \"welcome_v2\",\n  \"language\": \"es\",\n  \"recipients\": [\n    {\n      \"to\": \"+5491155555555\",\n      \"variables\": {\n        \"nombre\": \"Juan\"\n      },\n      \"meta_data\": {}\n    }\n  ],\n  \"channel_id\": \"665f1a2b3c4d5e6f70819234\",\n  \"phone_number_id\": \"100000000000001\",\n  \"campaign_name\": \"Onboarding marzo 2026\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.keebai.com/v1/messages/bulk")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"template_name\": \"welcome_v2\",\n  \"language\": \"es\",\n  \"recipients\": [\n    {\n      \"to\": \"+5491155555555\",\n      \"variables\": {\n        \"nombre\": \"Juan\"\n      },\n      \"meta_data\": {}\n    }\n  ],\n  \"channel_id\": \"665f1a2b3c4d5e6f70819234\",\n  \"phone_number_id\": \"100000000000001\",\n  \"campaign_name\": \"Onboarding marzo 2026\"\n}"

response = http.request(request)
puts response.read_body

{
  "broadcast_id": "<string>",
  "status": "scheduled",
  "total_recipients": 123,
  "scheduled_at": "<string>"
}

Send the same template to multiple recipients, with potentially different variables per recipient. Creates a broadcast in the database that you can track via GET /v1/messages/bulk/:broadcastId.

Endpoint

POST https://api.keebai.com/v1/messages/bulk

Required scope

messages:bulk

The messages:bulk scope is separate from messages:send precisely because bulk sending carries higher risk (Meta cost, sender number reputation, potential abuse). Grant it only to tokens controlled by the marketing tool or the job that needs to trigger campaigns.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer kbai_pk_<token>`
`Content-Type`	Yes	`application/json`

Body

Field	Type	Required	Description
`template_name`	`string`	Yes	Name of the approved template.
`language`	`string`	Yes	Template language code.
`channel_id`	`string`	No	Keebai channel id of the WhatsApp channel. Only needed when the project has more than one active WhatsApp channel.
`phone_number_id`	`string`	No	Alias for `channel_id`: the numeric id Meta issues for the sending number, not a Keebai `ObjectId`. List yours with `GET /v1/whatsapp/numbers`.
`campaign_name`	`string`	No	Human-readable name to identify the campaign in the portal. Auto-generated if omitted.
`recipients`	`array`	Yes	Between 1 and 5000 recipients. Each item: `{ to, variables?, meta_data? }`.

Structure of each `recipients[i]`

Field	Type	Required	Description
`to`	`string`	Yes	Phone number in E.164 format.
`variables`	`object<string, string>`	No	Template variables for this specific recipient.
`meta_data`	`object`	No	Free-form metadata persisted with this individual send.

Example request

curl -X POST https://api.keebai.com/v1/messages/bulk \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "promo_marzo_2026",
    "language": "es",
    "phone_number_id": "109876543210987",
    "campaign_name": "Promo marzo 2026 — clientes activos",
    "recipients": [
      { "to": "+5491155551111", "variables": { "nombre": "Juan" } },
      { "to": "+5491155552222", "variables": { "nombre": "Camila" } },
      { "to": "+5491155553333", "variables": { "nombre": "Joaquín" } }
    ]
  }'

const recipients = customers.map((c) => ({
  to: c.phone,
  variables: { nombre: c.first_name },
}));

await fetch("https://api.keebai.com/v1/messages/bulk", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template_name: "promo_marzo_2026",
    language: "es",
    phone_number_id: process.env.KEEBAI_PHONE_NUMBER_ID,
    campaign_name: "Promo marzo 2026",
    recipients,
  }),
});

import os, requests

recipients = [
    {"to": c["phone"], "variables": {"nombre": c["first_name"]}}
    for c in customers
]

resp = requests.post(
    "https://api.keebai.com/v1/messages/bulk",
    headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"},
    json={
        "template_name": "promo_marzo_2026",
        "language": "es",
        "phone_number_id": os.environ["KEEBAI_PHONE_NUMBER_ID"],
        "campaign_name": "Promo marzo 2026",
        "recipients": recipients,
    },
    timeout=30,
)
resp.raise_for_status()
broadcast_id = resp.json()["broadcast_id"]

Response

202 Accepted

{
  "broadcast_id": "65f4b5c6d7e8f9a0b1c2d3e4",
  "status": "PENDING",
  "total_recipients": 3,
  "scheduled_at": null
}

Field	Type	Description
`broadcast_id`	`string`	Broadcast id. Store it to check status later.
`status`	`string`	Initial status: `PENDING`. Switches to `IN_PROGRESS` once processing starts.
`total_recipients`	`number`	Number of accepted recipients.
`scheduled_at`	`string \| null`	Schedule date if applicable.

400 Bad Request

Invalid body: empty array, more than 5000 recipients, malformed phone number on any recipient.

401 Unauthorized

Missing, invalid, revoked, or expired token.

403 Forbidden

The token does not have the messages:bulk scope.

Best practices

Split very large batches. If your campaign has 50000 recipients, send 10 requests of 5000 each instead of fighting with timeouts. Use different campaign_name values to keep them distinct.
Deduplicate before sending. The API does not deduplicate by phone number — if you send the same recipient twice, the message goes out twice and Meta charges twice.
Keep variables consistent with the template. If the template expects {{nombre}} and {{monto}} and a recipient is missing monto, that individual send will fail. Validate the variable set up front.
Monitor status via GET /v1/messages/bulk/:broadcastId to detect campaigns with a high error rate.

Authorizations

Authorization

string

header

required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Body

application/json

template_name

string

required

Example:

"welcome_v2"

language

string

required

Example:

"es"

recipients

object[]

required

Required array length: 1 - 5000 elements

Show child attributes

channel_id

string

Keebai channel id. Optional when the tenant has exactly one active channel of the given type; required to disambiguate otherwise.

Example:

"665f1a2b3c4d5e6f70819234"

phone_number_id

string

WhatsApp-only alias for channel_id: the Meta phone_number_id of the sending number. Ignored on other channels.

Example:

"100000000000001"

campaign_name

string

Example:

"Onboarding marzo 2026"

Response

202 - application/json

broadcast_id

string

required

status

string

required

Example:

"scheduled"

total_recipients

number

required

scheduled_at

string | null

POST messages/raw GET messages/bulk/:id

Get started

Contacts

WhatsApp

WhatsApp Flows

Templates

Channels

POST /v1/messages/bulk

Endpoint

Required scope

Headers

Body

Structure of each `recipients[i]`

Example request

Response

202 Accepted

400 Bad Request

401 Unauthorized

403 Forbidden

Best practices

Authorizations

Body

Response

​Endpoint

​Required scope

​Headers

​Body

​Structure of each recipients[i]

​Example request

​Response

​202 Accepted

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​Best practices

Authorizations

Body

Response

Endpoint

Required scope

Headers

Body

Structure of each `recipients[i]`

Example request

Response

202 Accepted

400 Bad Request

401 Unauthorized

403 Forbidden

Best practices