# 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`)

## Descripcion 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` | List approved WhatsApp templates |
| `GET` | `/v1/templates/:id` | Get template detail |
| `POST` | `/v1/templates/:id/send` | Send template to a contact |
| `GET` | `/v1/channels/:channel_id/templates` | Approved templates of one WhatsApp line |
| `GET` | `/v1/campaigns/:key/executions` | Delivery status per recipient (sends made with a campaign key) |

## 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 segun 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 envio solo significa que Meta ACEPTO el mensaje; entregado / leido / fallido llegan minutos despues por webhooks de Meta. Para leerlos, pasa `campaign` {key, name} en el body del envio (el envio queda registrado bajo esa clave, visible tambien en Plataforma → Campanas) y consulta este endpoint. `status` es sent, delivered, read o failed; `message_id` es el wamid que devuelve el envio (tambien viene en la respuesta del envio).

`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."
  }
}
```