smarttalkappdocs
API v1

Conecta tu producto a WhatsApp en minutos.

Una sola integración para enviar y recibir mensajes de WhatsApp Business desde tu sistema. Bearer-token por canal, idempotencia nativa, webhooks firmados, errores tipados. Diseñada para flujos productivos como cgmoda-style.

Quick startOpenAPI 3.1
01

Quick start

  1. 1

    Crea un canal de WhatsApp

    En la app, ve a Settings → WhatsApp → Conectar. Vincula tu número Meta Business y dejas el canal en estado active.
  2. 2

    Genera tu API token

    En Settings → WhatsApp → API token → Regenerar obtienes un string stk_xxx de 64 caracteres. Guárdalo con cuidado; puedes rotarlo en cualquier momento.
  3. 3

    Envía tu primer mensaje

    bash
    curl -X POST https://www.smarttalkapp.com/api/v1/messages/text \
  -H "Authorization: Bearer stk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "to": "573108760539",
    "text": "Hola desde mi integración"
  }'
    Si todo está bien, el endpoint devuelve 201 con un wa_message_id de Meta.
02

Autenticación

Todas las llamadas a /api/v1/* exigen el header Authorization: Bearer stk_…. El token está asociado a un solo canal de WhatsApp y a la organización dueña del canal — no a un usuario. Si necesitas multi-canal, emite un token por canal.

Buenas prácticas

  • No hardcodees el token en el cliente — guárdalo server-side.
  • Rotalo si lo expones por error. La rotación es instantánea.
  • Usa Idempotency-Key: <uuid> en cada POST para reintentos seguros (TTL 24h).
  • Incluye x-request-id para correlación cliente↔servidor.
03

Mensajes

POST/messages/text

Enviar un mensaje de texto

Soporta dentro de la ventana 24h. Fuera de ventana, devuelve 403 y debes usar /messages/template.

Request body

json
{
  "to": "573108760539",
  "text": "Hola, tu pedido sale hoy.",
  "contact_name": "Diana",
  "channel_id": 468350
}

Response 200

json
{
  "ok": true,
  "message_id": "uuid",
  "wa_message_id": "wamid.HBg...",
  "conversation_id": "uuid",
  "contact_id": "uuid",
  "status": "sent",
  "sent_at": "2026-05-19T05:13:19.570Z"
}
POST/messages/template

Enviar plantilla pre-aprobada

Funciona fuera de la ventana 24h. Los nombres deben coincidir con tus templates aprobados en Meta Business Manager.

Request body

json
{
  "to": "573108760539",
  "name": "despacho",
  "language": "es_CO",
  "body_params": ["Diana", "INTER-1234"],
  "contact_name": "Diana"
}

Response 200

json
{ "ok": true, "wa_message_id": "wamid.HBg...", ... }
POST/messages/media

Enviar media (imagen, video, audio, documento)

Meta descarga el binario del media_url y lo renderiza nativo en WhatsApp.

Request body

json
{
  "to": "573108760539",
  "type": "image",
  "media_url": "https://cdn.tuapp.com/foto.jpg",
  "caption": "Tu pedido.",
  "contact_name": "Diana"
}

Response 200

json
{ "ok": true, "wa_message_id": "wamid.HBg...", ... }
GET/messages/recent?limit=50

Listar los últimos N mensajes del canal

04

Contactos

GET/contacts/{id}

Lookup por UUID interno

GET/contacts/by-phone/{phone}

Lookup por número (digits only)

05

Health

GET/health

Liveness probe

Response 200

json
{
  "ok": true,
  "version": "v1",
  "deployment": "dpl_xxx",
  "channels_active": 2,
  "now": "2026-05-19T..."
}
06

Códigos de error

Todos los errores devuelven un shape consistente con un request_id para correlación. Los errores de WhatsApp Cloud API se traducen a códigos accionables.

json
{
  "error": {
    "code": "forbidden",
    "message": "The 24-hour WhatsApp customer service window has expired...",
    "meta": {
      "meta_code": 131047,
      "classification": "outside_24h_window",
      "hint": "POST /api/v1/messages/template"
    }
  },
  "request_id": "req_xxx"
}
StatusCodeClassificationSignificado
400invalid_request—Body inválido (zod), JSON malformado.
401unauthorized—Bearer ausente, malformado o inválido.
403forbiddenoutside_24h_windowLa ventana 24h expiró. Usa /messages/template.
403forbiddenchannel_inactiveChannel en status disconnected/error.
422invalid_requestinvalid_recipientEl número no es WhatsApp válido.
422invalid_requesttemplate_disapprovedTemplate paused/rejected en Meta.
429provider_errorrate_limitedMeta rate limit. Backoff exponencial.
502provider_errorunknownError genérico del provider WhatsApp.
503internal_errorauth_failedAccess token del channel inválido/expirado.
07

Rate limits

CapaLímiteHeaders
smarttalkapp60 req/min por tokenX-RateLimit-Remaining
WhatsApp Cloud (Meta)Variable por tier (250 → 100k+ /24h)429 → backoff exp.
Idempotencia24h TTL por Idempotency-Keyreplay devuelve la respuesta original
08

Changelog

  • 2026-05-19 — clasificación de errores Meta (outside_24h_window, invalid_recipient, rate_limited, …).
  • 2026-05-18 — primeros endpoints públicos /messages/text|template|media, /contacts/*, /health.