API
Plantillas
Lista y envia plantillas de mensajes WhatsApp aprobadas
# Plantillas > Lista y envia plantillas de mensajes WhatsApp aprobadas - Página: https://tbit.app/es/docs/api/templates - URL base: `https://rest-api.tbit.app/v1` - Autenticación: encabezado `X-API-Key` con tu clave en cada solicitud (los ejemplos la leen de la variable de entorno `TBIT_API_KEY`) ## Descripción general Las plantillas son formatos de mensajes WhatsApp pre-aprobados requeridos para iniciar conversaciones fuera de la ventana de mensajeria de 24 horas. Solo las plantillas con estado aprobado por Meta pueden ser enviadas. ## Endpoints | Método | Ruta | Descripción | | --- | --- | --- | | `GET` | `/v1/templates` | Listar plantillas de WhatsApp aprobadas | | `GET` | `/v1/templates/:id` | Obtener detalle de plantilla | | `POST` | `/v1/templates/:id/send` | Enviar plantilla a un contacto | | `GET` | `/v1/channels/:channel_id/templates` | Plantillas aprobadas de una línea de WhatsApp | | `GET` | `/v1/campaigns/:key/executions` | Estado de entrega por destinatario (envíos hechos con una clave de campaña) | ## Listar Plantillas `GET /v1/templates` ```bash curl "https://rest-api.tbit.app/v1/templates" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## Obtener Detalle de Plantilla `GET /v1/templates/tpl_abc123` ```bash curl "https://rest-api.tbit.app/v1/templates/tpl_abc123" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## Plantillas por linea de WhatsApp Una plantilla se aprueba en una sola cuenta de WhatsApp Business, asi que un agente con varias lineas tiene un conjunto de plantillas por linea. GET /v1/templates mezcla todas las lineas (cada item trae su channel_id); usa este endpoint para listar solo lo que una linea puede enviar. El id del canal es el que se ve en Plataforma → Canales. `GET /v1/channels/6a7268abec6ecaf999a6c0ba/templates` ```bash curl "https://rest-api.tbit.app/v1/channels/6a7268abec6ecaf999a6c0ba/templates" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## Enviar Plantilla Nota de Envio El arreglo de componentes sigue el formato de la API de WhatsApp Business. Incluye componentes de encabezado, cuerpo y botones según lo requiera tu plantilla. `POST /v1/templates/tpl_abc123/send` ```bash curl -X POST "https://rest-api.tbit.app/v1/templates/tpl_abc123/send" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "573001234567", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "John" }, { "type": "text", "text": "your order #1234" } ] } ] }' ``` ## Estado de entrega La respuesta del envío solo significa que Meta ACEPTÓ el mensaje; entregado / leído / fallido llegan minutos después por webhooks de Meta. Para leerlos, pasa `campaign` {key, name} en el body del envío (el envío queda registrado bajo esa clave, visible también en Plataforma → Campañas) y consulta este endpoint. `status` es sent, delivered, read o failed; `message_id` es el wamid que devuelve el envío (también viene en la respuesta del envío). `GET /v1/campaigns/my-app/executions` ```bash curl "https://rest-api.tbit.app/v1/campaigns/my-app/executions?since=2026-08-27T00:00:00Z&limit=100" \ -H "X-API-Key: $TBIT_API_KEY" ``` Respuesta: ```json { "data": [ { "id": "6a90ea1f...", "to": "573001234567", "template_id": "tpl_abc123", "message_id": "wamid.HBgLNTcz...", "status": "failed", "error_message": "This message was not delivered to maintain healthy ecosystem engagement.", "sent_at": "2026-08-28T02:17:59.494Z", "delivered_at": null, "read_at": null } ] } ``` ## Formato de Respuesta Un objeto de plantilla: ```json { "data": [ { "id": "tpl_abc123", "name": "order_confirmation", "language": "es", "status": "APPROVED", "category": "UTILITY", "channel_id": "6a7268abec6ecaf999a6c0ba", "components": [ { "type": "BODY", "text": "Hola {{1}}, {{2}} ha sido confirmado." } ], "created_at": "2024-08-15T10:00:00Z" } ] } ``` ## Respuesta de Envio Un envio exitoso retorna el ID del mensaje: ```json { "data": { "message_sent": true, "message_id": "wamid.HBgLNTczMDAxMjM0NTY3FQIAERgSMUY2RUZGM0Y3RTJCRTQ5AA==", "parsed_message": "Hola John, your order #1234 ha sido confirmado." } } ```Las plantillas son formatos de mensajes WhatsApp pre-aprobados requeridos para iniciar conversaciones fuera de la ventana de mensajeria de 24 horas. Solo las plantillas con estado aprobado por Meta pueden ser enviadas.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /v1/templates | Listar plantillas de WhatsApp aprobadas |
| GET | /v1/templates/:id | Obtener detalle de plantilla |
| POST | /v1/templates/:id/send | Enviar plantilla a un contacto |
| GET | /v1/channels/:channel_id/templates | Plantillas aprobadas de una línea de WhatsApp |
| GET | /v1/campaigns/:key/executions | Estado de entrega por destinatario (envíos hechos con una clave de campaña) |
/v1/templatescurl "https://rest-api.tbit.app/v1/templates" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/templates', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/templates',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/templates',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/templates');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);/v1/templates/tpl_abc123curl "https://rest-api.tbit.app/v1/templates/tpl_abc123" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/templates/tpl_abc123', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/templates/tpl_abc123',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/templates/tpl_abc123',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/templates/tpl_abc123');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);Una plantilla se aprueba en una sola cuenta de WhatsApp Business, asi que un agente con varias lineas tiene un conjunto de plantillas por linea. GET /v1/templates mezcla todas las lineas (cada item trae su channel_id); usa este endpoint para listar solo lo que una linea puede enviar. El id del canal es el que se ve en Plataforma → Canales.
/v1/channels/6a7268abec6ecaf999a6c0ba/templatescurl "https://rest-api.tbit.app/v1/channels/6a7268abec6ecaf999a6c0ba/templates" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/channels/6a7268abec6ecaf999a6c0ba/templates', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/channels/6a7268abec6ecaf999a6c0ba/templates',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/channels/6a7268abec6ecaf999a6c0ba/templates',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/channels/6a7268abec6ecaf999a6c0ba/templates');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);Nota de Envio
El arreglo de componentes sigue el formato de la API de WhatsApp Business. Incluye componentes de encabezado, cuerpo y botones según lo requiera tu plantilla.
/v1/templates/tpl_abc123/sendcurl -X POST "https://rest-api.tbit.app/v1/templates/tpl_abc123/send" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "573001234567",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "John"
},
{
"type": "text",
"text": "your order #1234"
}
]
}
]
}'const response = await fetch('https://rest-api.tbit.app/v1/templates/tpl_abc123/send', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '573001234567',
components: [
{
type: 'body',
parameters: [
{
type: 'text',
text: 'John',
},
{
type: 'text',
text: 'your order #1234',
},
],
},
],
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/templates/tpl_abc123/send',
{
to: '573001234567',
components: [
{
type: 'body',
parameters: [
{
type: 'text',
text: 'John',
},
{
type: 'text',
text: 'your order #1234',
},
],
},
],
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/templates/tpl_abc123/send',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '573001234567',
'components': [
{
'type': 'body',
'parameters': [
{
'type': 'text',
'text': 'John',
},
{
'type': 'text',
'text': 'your order #1234',
},
],
},
],
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/templates/tpl_abc123/send');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '573001234567',
'components' => [
[
'type' => 'body',
'parameters' => [
[
'type' => 'text',
'text' => 'John',
],
[
'type' => 'text',
'text' => 'your order #1234',
],
],
],
],
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);La respuesta del envío solo significa que Meta ACEPTÓ el mensaje; entregado / leído / fallido llegan minutos después por webhooks de Meta. Para leerlos, pasa `campaign` {key, name} en el body del envío (el envío queda registrado bajo esa clave, visible también en Plataforma → Campañas) y consulta este endpoint. `status` es sent, delivered, read o failed; `message_id` es el wamid que devuelve el envío (también viene en la respuesta del envío).
/v1/campaigns/my-app/executionscurl "https://rest-api.tbit.app/v1/campaigns/my-app/executions?since=2026-08-27T00:00:00Z&limit=100" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/campaigns/my-app/executions?since=2026-08-27T00:00:00Z&limit=100', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/campaigns/my-app/executions?since=2026-08-27T00:00:00Z&limit=100',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/campaigns/my-app/executions?since=2026-08-27T00:00:00Z&limit=100',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/campaigns/my-app/executions?since=2026-08-27T00:00:00Z&limit=100');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": [
{
"id": "6a90ea1f...",
"to": "573001234567",
"template_id": "tpl_abc123",
"message_id": "wamid.HBgLNTcz...",
"status": "failed",
"error_message": "This message was not delivered to maintain healthy ecosystem engagement.",
"sent_at": "2026-08-28T02:17:59.494Z",
"delivered_at": null,
"read_at": null
}
]
}Un objeto de plantilla:
{
"data": [
{
"id": "tpl_abc123",
"name": "order_confirmation",
"language": "es",
"status": "APPROVED",
"category": "UTILITY",
"channel_id": "6a7268abec6ecaf999a6c0ba",
"components": [
{
"type": "BODY",
"text": "Hola {{1}}, {{2}} ha sido confirmado."
}
],
"created_at": "2024-08-15T10:00:00Z"
}
]
}Un envio exitoso retorna el ID del mensaje:
{
"data": {
"message_sent": true,
"message_id": "wamid.HBgLNTczMDAxMjM0NTY3FQIAERgSMUY2RUZGM0Y3RTJCRTQ5AA==",
"parsed_message": "Hola John, your order #1234 ha sido confirmado."
}
}