Saltar al contenido
Desarrolladores
4 min de lectura

Mensajes

Envía mensajes SMS, MMS o de WhatsApp, consulta la actividad reciente y archiva una conversación.

Compartir artículo

El envío es el endpoint que gasta dinero, así que es el que hay que tratar con más cuidado. Cada destinatario debe existir ya como contacto, y cada envío debería llevar una clave de idempotencia.

Antes de enviar

  • Crea primero el contacto con la sincronización de contactos. Un número que no es un contacto se rechaza.
  • Envía una clave de idempotencia para que un reintento no pueda duplicar el mensaje.
  • Vigila el límite de solicitudes para las acciones que gastan dinero.

Enviar un mensaje

Proporciona un cuerpo, una URL de contenido multimedia o un id de plantilla. Los mensajes se ponen en cola para su entrega y no se pueden recuperar una vez encolados.

POST /v0/account/{account_id}/message
curl -X POST https://api.furcata.com/v0/account/acc_123/message \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c1a9e4b2d4c8fa1b6e0d5c9f2a7b3" \
  -d '{
    "recipients": ["+15555550100"],
    "body": "Your table is ready.",
    "type": "sms",
    "language": "en"
  }'
Response
[
  {
    "id": "msg_123",
    "contact": "+15555550100",
    "status": "queued",
    "timestamp": "2026-01-01T00:00:00.000Z"
  }
]

Campos de la solicitud:

  • recipients: obligatorio, de uno a cincuenta números de teléfono en formato E.164.
  • body: hasta 1600 caracteres. Obligatorio cuando no se proporcionan media ni template.
  • media: una URL HTTPS, de hasta 2048 caracteres, para mensajes multimedia.
  • template: un id de plantilla guardada, de hasta 128 caracteres. Cuando está presente, reemplaza a body y media.
  • type: sms, mms o whatsapp. Por defecto es sms.
  • language: código de idioma de dos letras.

La respuesta es un acuse por destinatario, cada uno con id, contact, status y timestamp. Un 201 significa que los mensajes se aceptaron para su entrega, no que ya hayan llegado.

El envío no se puede deshacer

Una vez que un mensaje está en cola, se despacha y no se puede recuperar. Prueba con tu propio número antes de enviar a una audiencia real y envía siempre una clave de idempotencia para que un reintento tras un tiempo de espera agotado no envíe dos veces.

Listar los mensajes recientes

Devuelve los mensajes entrantes y salientes más recientes de la cuenta. Pasa direction para limitar la lista a un lado de la conversación.

GET /v0/account/{account_id}/message
curl "https://api.furcata.com/v0/account/acc_123/message?direction=outbound" \
  -H "Authorization: ******"
Response
[
  {
    "id": "msg_123",
    "contact": "+15555550100",
    "direction": "outbound",
    "type": "sms",
    "body": "Your table is ready.",
    "media": null,
    "language": "en",
    "sentiment": null,
    "country": "US",
    "status": "delivered",
    "timestamp": "2026-01-01T00:00:00.000Z"
  }
]

direction acepta inbound u outbound. Cada mensaje lleva id, contact, direction, type, body, media, language, sentiment, country, status y timestamp.

Archivar una conversación

Archivar oculta una conversación de la lista activa y registra quién lo hizo. También puedes marcar al contacto como dado de baja al mismo tiempo. Esto solo cambia registros: no se envía ningún mensaje y no se cobra nada.

Este endpoint requiere un administrador de la cuenta.

POST /v0/account/{account_id}/message/archive
curl -X POST https://api.furcata.com/v0/account/acc_123/message/archive \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": "+15555550100",
    "unsubscribe": false
  }'
Response
{
  "message": "Conversation archived",
  "status": "archived"
}

contact es obligatorio y unsubscribe es false por defecto.

Errores

  • 400 cuando recipients está vacío, un número no está en formato E.164 o no se indica body, media ni template.
  • 401 cuando falta el token o no se acepta.
  • 403 cuando alguien que no es administrador de la cuenta intenta archivar.
  • 409 cuando llega un reintento mientras la primera solicitud con la misma clave de idempotencia sigue en curso.
  • 429 cuando superas el límite para las acciones que gastan dinero.

Siguientes pasos

Suscríbete a los eventos de webhook para saber cuándo se entrega un mensaje, cuándo falla o cuándo se responde.