Saltar al contenido

Apartado 6 de 15 · Sincronizar

Escribir en Chatendo: contactos y mensajes

Alta y edición de contactos, etiquetas, envío de mensajes por WhatsApp e Instagram, la ventana de 24 horas y los webhooks de entrada para sistemas sin token.

Revisado el API 1.158.0 22 min de lectura

En esta página (8)
  1. 6.1 · Contactos
  2. 6.2 · Mensajes
  3. 6.3 · La ventana de 24 horas
  4. 6.4 · Empujar sin token: los webhooks de entrada
  5. 6.5 · Lo que NO hay que hacer
  6. 6.6 · Conversaciones: guardar tu id (external_id)
  7. 6.7 · Una persona, varios canales
  8. 6.8 · Escribir a un teléfono nuevo y programar mensajes

6.1 · Contactos

Terminal
# Alta
curl -s -X POST "$API/contacts" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Accept: application/json' -H 'Content-Type: application/json' \
     -d '{"name":"Ana Ruiz","phone":"+34600111222"}'

# Edición
curl -s -X PATCH "$API/contacts/41" … -d '{"name":"Ana Ruiz Gómez"}'

# Etiquetas (reemplaza la lista entera, no añade)
curl -s -X PUT "$API/contacts/41/tags" … -d '{"tag_ids":[3,7]}'

phone es obligatorio y se normaliza a E.164. name es opcional.

El alta responde 201 con el contacto dentro de contact —{"contact":{"id":541,…}}—, y la lista lo trae dentro de data. No es la misma envoltura: léela según la ruta, o tu código buscará el id donde no está (medido el 22-09-2026).

POST /contacts NO es un upsert. Si el teléfono ya existe responde 422 PHONE_TAKEN y no escribe nada — probado. Para sincronizar usa PUT /contacts (abajo) o busca primero por teléfono o external_id.

Búsqueda exacta y upsert — para sincronizar no hace falta el q (es un LIKE):

Terminal
# 0 o 1 fila, nunca una lista. El teléfono se normaliza igual que en el alta:
# +34600111222, 0034600111222 y 600111222 son el mismo contacto.
curl -s -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
     "$API/contacts?phone=+34600111222"
curl -s -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
     "$API/contacts?external_id=CRM-7f3a9c"

# Crea (201) o actualiza (200); nunca da PHONE_TAKEN.
curl -s -X PUT "$API/contacts" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Accept: application/json' -H 'Content-Type: application/json' \
     -d '{"phone":"+34600111222","external_id":"CRM-7f3a9c","name":"Ana Ruiz"}'

PUT /contacts exige phone o external_id (al menos uno). Si mandas los dos y no casan con el mismo contacto —o el que casa es el perdedor de una fusión—, 409 CONTACT_CONFLICT con conflicting_contact_id (nunca PHONE_TAKEN); si el external_id no existe todavía y no mandas phone, 422 VALIDATION_ERROR con el error en errors.phone, porque hace falta para dar de alta. Llamarlo dos veces con el mismo cuerpo deja un único contacto, no dos. El external_id se compara como en §6.6: sin distinguir mayúsculas, acentos ni espacios al final.

6.2 · Mensajes

Terminal
curl -s -X POST "$API/conversations/2856/messages" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Accept: application/json' -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: pedido-9931-sale-hoy' \
     -d '{"type":"text","body":"Tu pedido sale hoy."}'

Necesita messages:send. Sin ese permiso responde 403 TOKEN_SCOPE_DENIED y no envía nada — comprobado en producción, que es como se prueba esto sin escribirle a una persona real.

El envío exige la cabecera Idempotency-Key (de 8 a 64 caracteres: letras, números, _, -, : o .): con la misma clave y el mismo cuerpo, un reintento tras un corte de red recibe la respuesta de la primera vez (con la cabecera Idempotent-Replay: true) y no manda el mensaje dos veces. Sin ella, 422 IDEMPOTENCY_KEY_REQUIRED; con la misma clave y otro cuerpo, 422 IDEMPOTENCY_KEY_REUSED. Lo mismo vale para los archivos (media-messages).

type admite: text, template, location, contacts, reaction, product, product_list y, solo en Instagram, quick_replies, button_template y generic_template. Texto libre: 4.096 caracteres en WhatsApp, 1.000 en Instagram. En una conversación de correo solo vale text (y archivos por media-messages), con otros límites: §15.5.

6.3 · La ventana de 24 horas

Regla de Meta, no de Chatendo. Fuera de las 24 h desde el último mensaje del cliente no sale texto libre: 422 WINDOW_EXPIRED, y no se envía nada.

Fuera de ventana solo pasa una plantilla aprobada (type: "template"). Que el cliente conteste vuelve a abrir la ventana.

Cada conversación te dice cuándo cierra, en window_expires_at y last_inbound_at. Si tu sistema manda avisos que pueden caer fuera, ten la plantilla aprobada antes, no el día que la necesites: Meta tarda en aprobarlas y rechaza, por ejemplo, cualquier plantilla cuya variable quede al principio o al final del texto.

Esta ventana es la de WhatsApp. Un buzón de correo no la tiene, ni usa plantillas (§15.5).

6.4 · Empujar sin token: los webhooks de entrada

Para sistemas que no pueden guardar un token —una tienda, un CRM— hay once puertas firmadas con HMAC contra el secreto del canal (shop_webhook_secret), fuera de /v1:

Puerta Para qué
POST /api/webhooks/shop-order · shop-order-v2 Un pedido nuevo de la tienda
POST /api/webhooks/shop-order-summary La ficha del pedido, compuesta por la tienda
POST /api/webhooks/shop-delivery-reminder Aviso de reparto
POST /api/webhooks/shop-order-reminder «Aún no has pedido»
POST /api/webhooks/contact-identity-v1 El CRM rellena nombre, empresa y código de cliente
POST /api/webhooks/lead-v1 Alguien dejó su número en una web y le escribimos nosotros
POST /api/webhooks/shop-company-account-approved Alta de cuenta de empresa aprobada
POST /api/webhooks/cupones/{tenant} Cupón canjeado
POST /api/webhooks/wa-admins-changed Cambió la lista de administradores

Dos detalles que ahorran una tarde:

  • contact-identity-v1 nunca crea un contacto, solo rellena los que ya existen. Si el contacto no está, no pasa nada y no hay error.
  • lead-v1 sí crea, y además escribe: el primer mensaje es siempre una plantilla aprobada. Sin plantilla no da de alta al contacto.

De dónde llegó el lead. lead-v1 acepta un objeto opcional procedencia con lo que tu web midió de esa visita: las etiquetas UTM, los identificadores de clic, la página de entrada y la web de la que venía. Chatendo decide el canal (Google Ads, Microsoft Ads, Meta Ads, TikTok Ads, LinkedIn Ads, ChatGPT Ads, un buscador, una red social, otra web o una visita directa) y lo enseña en la tarjeta «De dónde llegó» del contacto y bajo la cabecera de su conversación.

JSON
"procedencia": {
  "utm_source": "bing",
  "utm_medium": "cpc",
  "utm_campaign": "Primavera",
  "utm_term": "zapatillas de trail",
  "msclkid": "0f3b6c9e2d4a4b8f9e1c7a5d3b2f6e80",
  "landing": "https://www.tutienda.example/ofertas/trail",
  "referrer": "https://www.bing.com/"
}
  • Claves que se leen (las demás se ignoran): utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, gbraid, wbraid, gad_source, gad_campaignid, msclkid, fbclid, ttclid, li_fat_id, oppref, landing (la ruta o la URL completa de la página de entrada; de una URL completa se leen también sus etiquetas) y referrer (la página de la que venía). Se guarda solo la ruta de la página de entrada y el dominio de la de origen.
  • Nunca cuesta un lead. Si procedencia no es un objeto (un texto, un número, una lista) o trae más de 40 claves, se ignora entero y el lead entra igual, con la misma respuesta. Un identificador de clic que no tiene la forma esperada se descarta; los textos UTM se limpian y se recortan.
  • Un fbclid solo no es publicidad: Facebook e Instagram lo añaden a cualquier enlace, de pago o no, y cuenta como «Redes sociales». Para que un anuncio de Meta salga como Meta Ads, su enlace tiene que llevar utm_source=facebook (o instagram) y un utm_medium de pago, como cpc o paid_social.
  • Cuenta la primera vez. Si el contacto ya tenía una procedencia identificada, no se pisa; solo una visita directa o sin datos cede su sitio.
  • El origen del contacto. Si es publicidad y el contacto no tenía origen, pasa a ser «Publicidad · Microsoft Ads» (o la plataforma que sea; «Publicidad · Otra» si no se conoce). Lo que ya estaba escrito no se toca. Si tu integración está suscrita a contact.updated, ese cambio le llega una sola vez, con changes: ["origen"]. La nota interna del lead lleva además una línea «Procedencia: …» con el canal, la campaña y la búsqueda.
  • Para leerla: GET /api/v1/contacts/{id} y GET /api/v1/conversations/{id} devuelven procedencia_web (null si no se midió nada), con canal, plataforma, etiqueta, fuente, medio, campana, termino, contenido, campana_id, aterrizaje, referente, via, capturada_en y detalle. Las listas no la llevan.

El secreto de esas once puertas es del canal, no de tu integración. Si se lo das a dos sistemas y quieres echar a uno, tienes que rotarlo y romper el otro. Para eso existe la puerta de abajo.

Una puerta con secreto por integración: POST /api/webhooks/upsert-v1. Escribe contactos, etiquetas, campos propios, notas y citas, y está firmada con el secreto de una integración (se crea en Desarrolladores → Integraciones, junto a «Tokens de API», con sesión de propietario o administrador; el secreto se enseña una sola vez). Revocar una integración no rompe las demás. Nunca envía nada a nadie: no manda mensajes ni plantillas ni crea conversaciones.

  • Firma: X-Chatendo-Signature: sha256=<hmac-sha256 del cuerpo crudo> (el alias antiguo X-Vertichat-Signature también vale). Con X-Chatendo-Integration: <id> se comprueba solo contra esa integración, que tiene que estar activa. Sin firma válida: 401 INVALID_SIGNATURE, siempre con el mismo cuerpo.
  • Cuerpo: {"idempotency_key", "entity", "op", "match", "data"}. entity es contact, contact_tags, contact_fields, note o appointment; op es upsert o delete; match dice a qué contacto se refiere (phone o external_id). Solo upsert de contact crea contactos: las demás entidades exigen que el contacto exista (422 CONTACT_NOT_FOUND, y 404 MATCH_NOT_FOUND en delete).
  • Idempotencia: la misma idempotency_key con el mismo cuerpo devuelve el primer 200 con replayed: true y no escribe nada; con otro cuerpo, 409 IDEMPOTENCY_KEY_CONFLICT. Un teléfono o external_id que ya es de otro contacto: 409 CONTACT_CONFLICT.
  • Límites: cuerpo de hasta 1 MiB y 300 peticiones por minuto por IP (413, 429 RATE_LIMITED).
JSON
{"idempotency_key": "crm-7f3a9c-0001", "entity": "contact", "op": "upsert",
 "match": {"phone": "+34600111222"}, "data": {"name": "Ana Ruiz", "external_id": "CLI-00417"}}

Respuesta: {"ok": true, "entity": "contact", "op": "upsert", "id": 5123, "created": true, "replayed": false}.

6.5 · Lo que NO hay que hacer

  • No reintentes una escritura a ciegas. Manda Idempotency-Key (§6.2): con la misma clave y el mismo cuerpo, un reintento tras un corte de red recibe la respuesta de la primera vez (se guarda 24 horas) y no crea el contacto ni manda el mensaje dos veces. En los envíos de mensajes y de archivos es obligatoria; en una ruta que no la mire, un reintento sí duplica: comprueba antes de reintentar.
  • No uses el token desde el navegador del cliente. Es una llave de tu cuenta: va en tu servidor.
  • No borres conversaciones por API aunque encuentres la ruta: conversations:write no se le da a un token de fuera a propósito.
  • No inventes parámetros. En las rutas de lectura, un parámetro que la ruta no conoce da 422 UNKNOWN_QUERY_PARAM, con los que sí admite en allowed (y UNKNOWN_BODY_FIELD si es un campo del cuerpo): un filtro mal escrito ya no te devuelve la colección entera. Si en una lista pasas varios valores donde solo cabe uno (?q[]=a), da 422 INVALID_QUERY_PARAM.

6.6 · Conversaciones: guardar tu id (external_id)

Igual que en los contactos, una conversación puede guardar el id que tiene en tu sistema:

conversations:write no se marca en Desarrolladores → Tokens de API (§3): con un token creado allí este PATCH da 403 TOKEN_SCOPE_DENIED. Si tu integración lo necesita, se pide y se acuña desde el servidor.

Terminal
# Guardarlo (null lo borra). Necesita conversations:write.
curl -s -X PATCH "$API/conversations/2856" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Accept: application/json' -H 'Content-Type: application/json' \
     -d '{"external_id":"CRM-LEAD-2291"}'

# Buscarla luego: 0 o 1 fila, por igualdad, no un `q`. `filter=all` la
# encuentra también si está cerrada (sin `filter`, la lista solo trae las abiertas).
curl -s -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
     "$API/conversations?filter=all&external_id=CRM-LEAD-2291"
  • external_id es obligatorio en el cuerpo del PATCH (hasta 191 caracteres; mandar null lo borra). Cualquier otro campo en el cuerpo da 422 UNKNOWN_BODY_FIELD.
  • Es único por inquilino, contando las conversaciones de la papelera: si ya lo tiene otra, 422 VALIDATION_ERROR con el error en errors.external_id — a diferencia de PUT /contacts, aquí no hay un 409 CONTACT_CONFLICT con el id de quien lo tiene, solo el 422 de validación.
  • Una conversación de otro inquilino, o de un canal que no ves, da 404. Buscar el external_id de otro inquilino da una lista vacía, no un error.
  • ?external_id[]= (una lista) no es el mismo parámetro: da 422.
  • La igualdad es la de la base de datos de producción: no distingue mayúsculas, acentos ni espacios al final. CRM-LEAD-1, crm-lead-1 y CRM-LEAD-1 son el mismo id: la búsqueda devuelve la conversación que lo tenga y un segundo PATCH con la variante da 422. Si en tu sistema dos ids solo se diferencian en eso, no los guardes tal cual.

6.7 · Una persona, varios canales

La misma persona puede escribirte por WhatsApp, por Instagram y por correo. Chatendo la guarda como un contacto y una conversación por canal —cada una con su ventana de 24 horas, sus plantillas y su estado— y, desde la versión 1.53 (22-10-2026), el equipo puede enlazar esos contactos como «la misma persona»: el panel los enseña en un solo chat, con cada canal diferenciado y la opción de contestar por cualquiera de ellos. Desde la API se puede:

  • agrupar en tu sistema las conversaciones de una misma persona, con persona.key, en vez de crear una ficha por canal;
  • decirle a Chatendo que dos contactos son la misma persona cuando tu sistema ya lo sabe (o que no lo son);
  • contestar por el canal que toque, que sigue siendo enviar a la conversación de ese canal.

Enlazar no es fusionar. No se borra ni se mueve ningún contacto, conversación ni mensaje; cada canal conserva su ventana y sus plantillas; y se deshace con una llamada. POST /contacts/{id}/merge (§4.1), en cambio, borra al contacto absorbido y no se puede deshacer. Un contacto está como mucho en un grupo, y los de LinkedIn no se enlazan con nadie.

Las respuestas de abajo son capturas literales del 22-10-2026, de un entorno de pruebas con el código de la 1.53 y un token de verdad; los datos son inventados («Tienda Aurora», direcciones .test). Donde dice «recortada», se ha quitado lo que no cambia.

Leer: el campo persona. GET /conversations y GET /conversations/{id} añaden persona solo cuando el contacto pertenece a un grupo; en cualquier otro caso la conversación responde lo de siempre, sin el campo (ni siquiera a null). Resume las conversaciones de la persona, la propia incluida, una por canal —la vigente: la abierta; si no hay, la pospuesta; si no, la cerrada más reciente— y de la que tuvo el último mensaje más reciente a la más antigua. Recortada (el resto es la conversación de siempre):

JSON
{
  "id": 1,
  "platform": "whatsapp",
  "contact_id": 1,
  "persona": {
    "key": "01M5GC2SW5CFM8XGKZJ40QZKRV",
    "contact_ids": [1, 2, 3],
    "hermanas": [
      { "id": 2, "contact_id": 2, "whatsapp_channel_id": 2, "platform": "instagram", "state": "open",
        "unread_count": 0, "assigned_user_id": null,
        "last_message_at": "2026-10-21T22:39:29Z", "last_inbound_at": "2026-10-21T22:39:29Z" },
      { "id": 1, "contact_id": 1, "whatsapp_channel_id": 1, "platform": "whatsapp", "state": "open",
        "unread_count": 0, "assigned_user_id": null,
        "last_message_at": "2026-10-21T21:42:29Z", "last_inbound_at": "2026-10-21T21:42:29Z" },
      { "id": 3, "contact_id": 3, "whatsapp_channel_id": 3, "platform": "email", "state": "open",
        "unread_count": 0, "assigned_user_id": null,
        "last_message_at": "2026-10-19T00:27:30Z", "last_inbound_at": "2026-10-18T23:37:30Z" }
    ]
  }
}

key es opaca (un ULID): vale para agrupar y comparar, no para construir direcciones, y puede cambiar si el grupo se deshace y se vuelve a enlazar o se funde con otro. Las conversaciones antiguas y ya cerradas de un canal no salen en hermanas; siguen en GET /conversations?filter=all.

Leer la persona entera. Sus contactos, cada uno con su plataforma de verdad; sus conversaciones completas; y a quién más podría ser. No hay una ruta «persona de un contacto»: se pregunta por una de sus conversaciones.

Terminal
curl -s -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
     "$API/conversations/1/persona"

Respuesta (recortada: cada conversación trae la misma forma que en GET /conversations, sin el campo persona):

JSON
{
  "data": {
    "key": "01M5GC2SW5CFM8XGKZJ40QZKRV",
    "automatico": false,
    "contactos": [
      { "id": 1, "platform": "whatsapp", "name": "Laura Pardo", "profile_name": "Laura",
        "phone_e164": "+34611000201", "ig_username": null, "email": "laura.pardo@ejemplo.test",
        "email_id": null, "declared_phone_e164": null },
      { "id": 2, "platform": "instagram", "name": "Laura Pardo", "profile_name": "Laura Pardo",
        "phone_e164": null, "ig_username": "laura.pardo.demo", "email": null,
        "email_id": null, "declared_phone_e164": null },
      { "id": 3, "platform": "email", "name": "Laura Pardo", "profile_name": "Laura Pardo",
        "phone_e164": null, "ig_username": null, "email": "laura.pardo@ejemplo.test",
        "email_id": "laura.pardo@ejemplo.test", "declared_phone_e164": null }
    ],
    "conversaciones": [
      { "id": 2, "platform": "instagram", "contact_id": 2, "state": "open", "…": "…" },
      { "id": 1, "platform": "whatsapp", "contact_id": 1, "state": "open", "…": "…" },
      { "id": 3, "platform": "email", "contact_id": 3, "state": "open", "…": "…" }
    ],
    "sugerencias": []
  }
}
  • key es null si el contacto no está enlazado con nadie: su persona es entonces solo él.
  • automatico es el ajuste de la cuenta «Unir automáticamente los chats de una misma persona» (Ajustes → General → «Un chat por persona»; apagado de serie). También sale en GET /tenant/settings, como unir_chats_automaticamente. Cambiarlo es cosa del equipo, desde el panel.
  • contactos va por orden de alta y cada uno trae su platform: GET /contacts solo la manda en web y correo, y con ella sabes si «Laura» es la de WhatsApp o la de Instagram. name es el nombre del contacto y, si no tiene, el de su perfil.
  • conversaciones va de la más reciente a la más antigua por su último mensaje, y trae la misma conversación vigente por canal que hermanas. Para saber si por un canal puedes escribir texto libre ahora, mira en cada una window_expires_at (§6.3); en el correo es null, porque no tiene ventana (§15.4).

Necesita conversations:read. Salen los chats que ese token ya podía ver —los canales que su usuario ve y, si su rol es de alcance «propios», los suyos y los sin asignar de sus canales (§3)—, y de los contactos del grupo, los de esos chats y los que su alcance de contactos deja ver: un contacto fuera de eso no sale ni con su nombre, ni con su usuario de Instagram, ni con su correo. Una conversación que no existe, es de otra cuenta o es de un canal que el token no ve da 404.

Sugerencias. Chatendo propone enlazar dos contactos cuando comparten el mismo correo o el mismo teléfono —el que dieron, nunca el nombre: dos «Ana García» no son una persona—. Quedan fuera los contactos del equipo, los de LinkedIn y los que alguien ya dijo que no. Aquí el WhatsApp de Carlos y su correo comparten dirección (GET /conversations/4/persona, antes de enlazarlos; solo el bloque nuevo):

JSON
"sugerencias": [
  {
    "contacto": {
      "id": 5, "platform": "email", "name": "Carlos Ibáñez", "profile_name": "Carlos Ibáñez",
      "phone_e164": null, "ig_username": null, "email": "carlos.ibanez@ejemplo.test",
      "email_id": "carlos.ibanez@ejemplo.test", "declared_phone_e164": null
    },
    "motivos": ["correo"],
    "segura": true,
    "conversaciones": [ { "id": 5, "whatsapp_channel_id": 3, "platform": "email" } ]
  }
]

motivos son correo, telefono o los dos; conversaciones son los chats de ese contacto que el token puede ver (si no ve ninguno, esa sugerencia no sale), y salen como mucho cinco sugerencias. segura: true quiere decir que es la única coincidencia y que la persona resultante no tendría dos contactos de la misma plataforma. Con el ajuste «unir automáticamente» encendido, Chatendo enlaza él solo las segura cuando entra un mensaje de ese contacto; las demás las decide una persona del equipo o tu integración, con las llamadas de abajo. Sugerir no es unir: leer las sugerencias no cambia nada.

Buscar a mano a quién enlazar, para lo que Chatendo no sabe sugerir —quien escribe desde otro número o con otro correo—:

Terminal
curl -s -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
     "$API/conversations/1/persona/buscar?q=carlos"
JSON
{
  "data": [
    { "id": 5, "platform": "email", "name": "Carlos Ibáñez", "profile_name": "Carlos Ibáñez",
      "phone_e164": null, "ig_username": null, "email": "carlos.ibanez@ejemplo.test",
      "email_id": "carlos.ibanez@ejemplo.test", "declared_phone_e164": null },
    { "id": 4, "platform": "whatsapp", "name": "Carlos Ibáñez", "profile_name": "Carlos",
      "phone_e164": "+34611000302", "ig_username": null, "email": "carlos.ibanez@ejemplo.test",
      "email_id": null, "declared_phone_e164": null }
  ]
}

Devuelve hasta 8 contactos con la misma forma que en contactos: primero los que empiezan por lo escrito y después los más recientes.

  • Busca por nombre, teléfono (con o sin espacios, guiones o «+»; a partir de 4 cifras), @usuario de Instagram (con o sin arroba) o correo.
  • Con menos de dos letras, o sin q, contesta la lista vacía y no un error: la llama una caja de texto que se va rellenando. Lo escrito se recorta a 100 caracteres, y % y _ se buscan tal cual (q=%25%25 no devuelve toda la agenda).
  • La lista ya viene filtrada: no salen los contactos que ya son esa persona, ni los del equipo, ni los de LinkedIn.
  • Pide conversations:read y además contacts:read o contacts:write, porque devuelve contactos. Con solo conversations:read: 403 TOKEN_SCOPE_DENIED con "required":["contacts:read","contacts:write"]. Y el rol de quien creó el token necesita contactos.ver: con solo conversaciones.ver, 403 FORBIDDEN.
  • Un parámetro que la ruta no conoce da 422 UNKNOWN_QUERY_PARAM (en allowed va lo que sí admite: aquí solo q; GET /conversations/{id}/persona no admite ninguno).

Escribir: enlazar, separar, descartar. Las tres piden contacts:write y se pueden repetir sin daño. Los ids de estas rutas son de contacto, no de conversación.

Terminal
# Enlazar: «el contacto 4 y el 5 son la misma persona»
curl -s -X POST "$API/contacts/4/persona" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Accept: application/json' -H 'Content-Type: application/json' \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{"contact_id":5}'

Responde 200 con la clave del grupo y los contactos que tu token puede ver:

JSON
{
  "data": {
    "key": "01M5GD9DSST3FB253TAKHNR9JP",
    "contactos": [
      { "id": 4, "platform": "whatsapp", "name": "Carlos Ibáñez", "profile_name": "Carlos",
        "phone_e164": "+34611000302", "ig_username": null, "email": "carlos.ibanez@ejemplo.test",
        "email_id": null, "declared_phone_e164": null },
      { "id": 5, "platform": "email", "name": "Carlos Ibáñez", "profile_name": "Carlos Ibáñez",
        "phone_e164": null, "ig_username": null, "email": "carlos.ibanez@ejemplo.test",
        "email_id": "carlos.ibanez@ejemplo.test", "declared_phone_e164": null }
    ]
  }
}

Si alguno ya tenía grupo, el otro se une a él; si estaban en grupos distintos, los dos grupos pasan a ser uno; si ya estaban juntos, no hace nada y vuelve a dar 200 con la misma key. Si el enlace sale de una sugerencia de Chatendo, añade "desde_sugerencia": true al cuerpo (opcional): queda anotado de dónde salió.

Terminal
# Separar: saca al contacto 5 de su grupo. No borra ni mueve nada.
curl -s -X DELETE "$API/contacts/5/persona" \
     -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
     -H "Idempotency-Key: $(uuidgen)"
# → 200 {"data":{"separado_de":[4]}}   (sin enlace: 200 {"data":{"separado_de":[]}})

# Descartar: «el 4 y el 5 NO son la misma persona». Deja de sugerirse.
curl -s -X POST "$API/contacts/4/persona/descartar" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Accept: application/json' -H 'Content-Type: application/json' \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{"contact_id":5}'
# → 200 {"data":{"descartado":true}}

Separar a alguien lo deja anotado como «no es la misma persona», igual que descartar: ni se vuelve a sugerir ni lo vuelve a enlazar la unión automática. Si te equivocaste, enlázalos otra vez a mano con el POST de arriba (se puede, y borra esa anotación). Si el grupo se queda con un solo contacto, deja de existir.

Idempotency-Key es opcional en estas tres rutas, pero mándala (§6.2, §6.5): con la misma clave y el mismo cuerpo, un reintento recibe la respuesta de la primera vez —la cabecera Idempotent-Replay: true lo dice— y con la misma clave y otro cuerpo da 422 IDEMPOTENCY_KEY_REUSED.

Errores (los de siempre están en el §8):

Código Qué pasó Qué hacer
422 SAME_CONTACT contact_id es el mismo contacto de la ruta Mandar el otro
422 PLATFORM_NOT_LINKABLE Uno de los dos contactos es de LinkedIn No se enlaza: LinkedIn se contesta desde el panel
404 CONTACT_NOT_FOUND El contacto de contact_id no existe, es de otra cuenta o queda fuera del alcance del token Comprobar el id con GET /contacts
404 NOT_FOUND El contacto de la ruta (o la conversación de las lecturas) no existe, es de otra cuenta, de un canal que no ves o queda fuera del alcance de conversaciones.ver de quien creó el token (también si su rol ve contactos pero ningún chat) Comprobar el id
422 VALIDATION_ERROR Falta contact_id o no es un número entero errors.contact_id lo dice
422 UNKNOWN_QUERY_PARAM Un parámetro de la URL que la ruta no conoce allowed dice cuáles admite
403 TOKEN_SCOPE_DENIED Falta contacts:write (enlazar, separar, descartar) o conversations:read (leer; buscar pide además contacts:read o contacts:write) required dice cuál
403 FORBIDDEN El rol de quien creó el token no puede (§3): contactos.editar para escribir, conversaciones.ver para leer la persona y contactos.ver para buscar GET /me/permissions

Lo que no cambia, y lo que no hay

  • Enviar no cambia. Para contestar a Laura por Instagram se envía a la conversación de Instagram, POST /conversations/2/messages (§6.2): no existe «el hilo de la persona». Para contestar donde escribió por última vez, elige de hermanas la de last_inbound_at más reciente. Cada conversación se sigue leyendo y paginando por separado (§7.3); es el panel quien junta los hilos al pintarlos. Y cada canal sigue con sus reglas: la ventana de 24 horas (§6.3) y el correo sin plantillas (§15.5).
  • Enlazar y separar no avisan ni mueven updated_at. No hay webhook de «se unió», y ni los contactos ni las conversaciones de la persona cambian su updated_at: GET /conversations?updated_since= no devuelve una conversación solo porque su persona cambió. Si tu sistema agrupa por persona, vuelve a leer persona (o GET /conversations/{id}/persona) cuando la tengas delante o cada cierto tiempo.
  • Cerrar, posponer y asignar siguen siendo de una conversación. En el panel, hacerlo sobre una persona lo repite en sus demás chats; por API es una llamada por conversación, como siempre.

6.8 · Escribir a un teléfono nuevo y programar mensajes

Escribir a un número sin conversación: POST /outbound-messages. Manda un WhatsApp a un teléfono aunque todavía no sea contacto ni tenga conversación. Pide messages:send y la cabecera Idempotency-Key (§6.2); sale siempre por el canal principal de WhatsApp de la cuenta (no se elige canal por petición: sin ninguno, 422 CHANNEL_UNAVAILABLE).

Terminal
curl -s -X POST "$API/outbound-messages" \
     -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' -H 'Content-Type: application/json' \
     -H "Idempotency-Key: aviso-factura-1340" \
     -d '{"phone":"+34612000111","name":"Bar Ejemplo",
          "body":"Hola, te recordamos la factura 1340, vencida el 01/09.",
          "template":{"name":"aviso_cobro_cliente","parameters":["la factura 1340, vencida el 01/09"]}}'
  • phone va en formato internacional con + (o con 00). Un número sin + ni 00 se toma por nacional de España.
  • Dentro de las 24 horas desde que el cliente escribió sale el body; fuera de ellas, o si no hay conversación, sale la plantilla aprobada que declares en template. Sin template en ese caso: 422 WINDOW_EXPIRED; con una que no existe o no está aprobada: 422 WINDOW_EXPIRED_TEMPLATE_UNAVAILABLE.
  • Si el teléfono ya es un contacto que está en la papelera (409 CONTACT_DELETED), de baja (409 CONTACT_OPTED_OUT) o sin WhatsApp (409 NUMBER_WITHOUT_WHATSAPP), no se escribe y no se crea nada. Un teléfono mal escrito: 422 PHONE_INVALID.
  • La respuesta (201) trae delivery (text o template: cómo salió de verdad), message, conversation_id, contact_id, contact_created y conversation_created. Si crea la conversación, la deja cerrada: un aviso no es un chat que el equipo tenga que atender. Si el cliente contesta, esa conversación se reabre.

Programar un mensaje: /conversations/{id}/scheduled-messages. Para que salga más tarde en una conversación que ya existe:

Ruta Qué hace
GET /conversations/{id}/scheduled-messages Los programados de esa conversación, por hora de salida
POST /conversations/{id}/scheduled-messages Programa uno: {"payload": {"type": "text", "body": "…"}, "send_at": "2026-12-01T09:00:00Z"} (o type: template con template_id y template_variables). Con un archivo, se manda multipart con file, caption y send_at (imagen, documento, vídeo o audio)
PATCH /conversations/{id}/scheduled-messages/{programado} Cambia la hora o el texto (de un archivo solo se cambia el pie)
DELETE /conversations/{id}/scheduled-messages/{programado} Cancela uno que aún no ha salido (204)

La hora tiene que estar al menos 60 segundos en el futuro (422 SEND_AT_TOO_SOON). Solo se cancela lo que está pendiente (422 CANNOT_CANCEL_NON_PENDING). No se puede añadir un archivo al editar un mensaje que no lo llevaba (422 ATTACHMENT_ON_EDIT_UNSUPPORTED): se cancela y se programa otro. En un canal de correo no se programan plantillas. Programar y cancelar piden messages:send (programar admite además Idempotency-Key, §6.5); listar, conversations:read.

Escríbenos por WhatsApp Te contesta nuestro agente de IA al momento