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.
En esta página (8)
6.1 · Contactos
# 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):
# 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
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 · shop-order-v2 |
Un pedido nuevo de la tienda |
POST /api |
La ficha del pedido, compuesta por la tienda |
POST /api |
Aviso de reparto |
POST /api |
«Aún no has pedido» |
POST /api |
El CRM rellena nombre, empresa y código de cliente |
POST /api |
Alguien dejó su número en una web y le escribimos nosotros |
POST /api |
Alta de cuenta de empresa aprobada |
POST /api |
Cupón canjeado |
POST /api |
Cambió la lista de administradores |
Dos detalles que ahorran una tarde:
contact-identity-v1nunca crea un contacto, solo rellena los que ya existen. Si el contacto no está, no pasa nada y no hay error.lead-v1sí 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.
"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) yreferrer(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
procedenciano 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
fbclidsolo 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 llevarutm_source=facebook(oinstagram) y unutm_mediumde pago, comocpcopaid_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 acontact.updated, ese cambio le llega una sola vez, conchanges: ["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}yGET /api/v1/conversations/{id}devuelvenprocedencia_web(nullsi no se midió nada), concanal,plataforma,etiqueta,fuente,medio,campana,termino,contenido,campana_id,aterrizaje,referente,via,capturada_enydetalle. 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 antiguoX-Vertichat-Signaturetambién vale). ConX-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"}.entityescontact,contact_tags,contact_fields,noteoappointment;opesupsertodelete;matchdice a qué contacto se refiere (phoneoexternal_id). Soloupsertdecontactcrea contactos: las demás entidades exigen que el contacto exista (422 CONTACT_NOT_FOUND, y404 MATCH_NOT_FOUNDendelete). - Idempotencia: la misma
idempotency_keycon el mismo cuerpo devuelve el primer200conreplayed: truey no escribe nada; con otro cuerpo,409 IDEMPOTENCY_KEY_CONFLICT. Un teléfono oexternal_idque 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).
{"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:writeno 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 enallowed(yUNKNOWN_BODY_FIELDsi 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), da422 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.
# 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_ides obligatorio en el cuerpo delPATCH(hasta 191 caracteres; mandarnulllo borra). Cualquier otro campo en el cuerpo da422 UNKNOWN_BODY_FIELD.- Es único por inquilino, contando las conversaciones de la papelera: si ya lo tiene otra,
422 VALIDATION_ERRORcon el error enerrors.external_id— a diferencia dePUT /contacts, aquí no hay un409 CONTACT_CONFLICTcon 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 elexternal_idde otro inquilino da una lista vacía, no un error. ?external_id[]=(una lista) no es el mismo parámetro: da422.- 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-1yCRM-LEAD-1son el mismo id: la búsqueda devuelve la conversación que lo tenga y un segundoPATCHcon la variante da422. 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):
{
"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.
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):
{
"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": []
}
}keyesnullsi el contacto no está enlazado con nadie: su persona es entonces solo él.automaticoes 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 enGET /tenant/settings, comounir_chats_automaticamente. Cambiarlo es cosa del equipo, desde el panel.contactosva por orden de alta y cada uno trae suplatform:GET /contactssolo la manda en web y correo, y con ella sabes si «Laura» es la de WhatsApp o la de Instagram.namees el nombre del contacto y, si no tiene, el de su perfil.conversacionesva de la más reciente a la más antigua por su último mensaje, y trae la misma conversación vigente por canal quehermanas. Para saber si por un canal puedes escribir texto libre ahora, mira en cada unawindow_expires_at(§6.3); en el correo esnull, 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):
"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—:
curl -s -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
"$API/conversations/1/persona/buscar?q=carlos"{
"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%25no 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:ready ademáscontacts:readocontacts:write, porque devuelve contactos. Con soloconversations:read:403 TOKEN_SCOPE_DENIEDcon"required":["contacts:read","contacts:write"]. Y el rol de quien creó el token necesitacontactos.ver: con soloconversaciones.ver,403 FORBIDDEN. - Un parámetro que la ruta no conoce da
422 UNKNOWN_QUERY_PARAM(enallowedva lo que sí admite: aquí soloq;GET /conversations/{id}/personano 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.
# 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:
{
"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ó.
# 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 |
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 dehermanasla delast_inbound_atmá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 suupdated_at:GET /conversations?updated_since=no devuelve una conversación solo porque su persona cambió. Si tu sistema agrupa por persona, vuelve a leerpersona(oGET /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).
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"]}}'phoneva en formato internacional con+(o con00). Un número sin+ni00se 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 entemplate. Sintemplateen 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) traedelivery(textotemplate: cómo salió de verdad),message,conversation_id,contact_id,contact_createdyconversation_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 |
Los programados de esa conversación, por hora de salida |
POST /conversations |
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 |
Cambia la hora o el texto (de un archivo solo se cambia el pie) |
DELETE /conversations |
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.