Inicio API e integraciones | Claves, endpoints y webhooks

🔗

API e integraciones | Claves, endpoints y webhooks

Clave de API, endpoints, webhooks e integraciones con otros sistemas.

Por Matheus and 8 otros

• 28 artículos

API: Importación de Contacto mediante integración con HubSpot

Importación de Contacto utilizando disparo de webhook en HubSpot Utilizando nuestro endpoint de importación, es posible crear o actualizar tus contactos en Cloud Chat a través de webhooks integrados en HubSpot. Ejemplo de configuración de webhook usando workflows en HubSpot Para crear un webhook de importación de contacto en un workflow de HubSpot, sigue los pasos a continuación. Paso 1: Crear el workflow En la barra lateral principal de HubSpot, pasa el ratón sobre el ícono de automatizaciones y luego haz clic en Flujos de trabajo para ser redirigido al panel de workflows: Al ingresar al panel, haz clic en Crear flujo de trabajo y luego selecciona la opción Desde cero: En la selección de configuración del tipo de workflow, selecciona Basado en contacto y haz clic en Siguiente: Paso 2: Configurar la solicitud del webhook Con la configuración inicial del workflow completada, ahora debemos construir el payload a enviar en el webhook. Para comenzar la configuración del webhook, haz clic en el botón de agregar acción (+): En el panel izquierdo, haz clic en Operaciones de datos y luego selecciona Envia un webhook: En el selector de método, elige la opción POST: Luego, completa la información de la URL del webhook y la clave API: Nota: La clave API debe configurarse en gestionar secretos. Finalmente, completa los campos de información del contacto para realizar el disparo: name (Nombre), phone_number (Teléfono), email, identifier (Identificador único del contacto), así como cualquier otro atributo personalizado disponible: Nota: Al menos uno entre los campos phone_number, email y identifier es obligatorio para la creación del contacto. Si el contacto existe en tu base, será actualizado con los campos enviados anteriormente. De lo contrario, se añadirá un nuevo contacto.

Última actualización el Oct 21, 2025

API: Importación de contacto individual

API: Importación de Contacto Para importar o actualizar un contacto individual a través de la API en Cloud Chat, envía una solicitud POST al endpoint a continuación con tu clave de acceso y los campos necesarios. ¿Quieres importar varios contactos a la vez? Usa el endpoint de Importación masiva de contactos a través de la API. Ambos endpoints tienen diferentes formatos de cuerpo — no los confundas. Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/external_import Encabezados | Encabezado | Valor | | --- | --- | | content-type | application/json | | api_access_token | Tu token de API | Cuerpo de la solicitud El cuerpo es un objeto JSON simple (plano), sin arreglos. Al menos uno de los campos phone_number, identifier o email debe estar presente. { "phone_number": "+5599123456789", "identifier": "CUSTOM_ID", "email": "[email protected]", "name": "Nombre del Contacto", "company_name": "Empresa X", "tags": "tag1, tag2, tag3", "ATRIBUTO_PERSONALIZADO": "valor" } Campos disponibles | Campo | Obligatorio | Descripción | | --- | --- | --- | | phone_number | Al menos 1 de los 3* | Teléfono en formato internacional con + (ej: +5511999998888) | | email | Al menos 1 de los 3* | Correo electrónico del contacto | | identifier | Al menos 1 de los 3* | Identificador externo único | | name | No | Nombre del contacto | | company_name | No | Nombre de la empresa | | tags | No | Etiquetas separadas por coma | | Campos personalizados | No | Usa la clave del atributo personalizado registrado en Cloud Chat | *Al menos uno entre phone_number, email o identifier debe ser informado. Ejemplo de solicitud (curl) curl -X POST \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/external_import' \ --header 'content-type: application/json' \ --header 'api_access_token: TU_TOKEN' \ --data '{ "phone_number": "+5599123456789", "name": "Nombre del Contacto", "email": "[email protected]", "company_name": "Empresa X", "tags": "tag1, tag2" }' Comportamiento de creación y actualización (upsert) Este endpoint crea un nuevo contacto o actualiza uno existente automáticamente. Para decidir si el contacto ya existe, el sistema busca en el siguiente orden de prioridad: 1. Primero busca por email 2. Si no se envió email, busca por identifier 3. Si no se envió identifier, busca por phone_number Importante: La búsqueda usa solo el primer campo disponible en el orden anterior. No intenta los campos siguientes si el primero no encuentra resultado. ⚠️ Atención — búsqueda exacta por número de teléfono: este endpoint hace lookup exacto por phone_number. No busca por variantes del número (por ejemplo, no encuentra el contacto +551133334444 cuando envías +5511933334444, ni viceversa). Si necesitas que la búsqueda considere variantes del número de teléfono brasileño (12 vs 13 dígitos, con o sin el dígito 9), usa el endpoint de importación masiva con api_version: "v2" (o normalize_lookup: true). Qué significa esto en la práctica Si deseas actualizar un contacto que ya existe por teléfono (por ejemplo, agregar un correo electrónico), y envías: { "phone_number": "+5511999998888", "email": "[email protected]" } El sistema buscará primero por email (porque el campo email está presente). Si [email protected] no existe en ningún contacto, no intentará buscar por phone_number. El resultado será un intento de crear un nuevo contacto, que puede fallar silenciosamente por conflicto de teléfono. Cómo hacerlo correctamente Para actualizar un contacto existente por teléfono, envía solo el teléfono como identificador en la primera llamada, sin el campo que deseas añadir como identificador: Paso 1 — Localiza el contacto (si necesitas el ID): curl -X GET \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/search?q=+5511999998888' \ --header 'api_access_token: TU_TOKEN' Paso 2 — Actualiza vía endpoint de actualización individual: curl -X PUT \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/{{CONTACT_ID}}' \ --header 'content-type: application/json' \ --header 'api_access_token: TU_TOKEN' \ --data '{"email": "[email protected]"}' Respuesta | Estado | Significado | | --- | --- | | 204 No Content | Solicitud procesada (sin cuerpo de respuesta) | | 422 Unprocessable Entity | Error de validación | Atención: El estado 204 indica que la solicitud fue recibida, pero no devuelve el contacto creado/actualizado. Si necesitas confirmar que la modificación fue aplicada, realiza una consulta al contacto después de la llamada. Diferencia entre este endpoint y la importación masiva | | Este endpoint (external_import) | Importación masiva (bulk_create) | | --- | --- | --- | | Cuándo usar | Importar/actualizar 1 contacto por llamada | Importar/actualizar varios contactos a la vez | | Formato del body | Objeto JSON simple (plano) | {"upsert": true, "data": [{...}, {...}]} | | Upsert | Siempre activo (automático) | Requiere la bandera "upsert": true | | Respuesta | 204 No Content (sin cuerpo) | 201 Created con resultado | | Búsqueda por variantes de teléfono | No disponible (lookup exacto) | Disponible con normalize_lookup: true o api_version: "v2" | ¡No mezcles los formatos! Si envías {"upsert": true, "data": [...]} a este endpoint (external_import), no funcionará. Este formato es exclusivo del endpoint de importación masiva (bulk_create). Dónde encontrar los parámetros de configuración - CLOUDCHAT_DOMAIN: El dominio visible en la URL del navegador al acceder a Cloud Chat - ACCOUNT_ID: En configuraciones de la cuenta - API_TOKEN: En https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings

Última actualización el Sep 22, 2026

Migração de histórico de tickets para o Cloud Chat

Ao migrar de outro helpdesk, as conversas antigas não vêm automaticamente — ficam na ferramenta anterior. Se quiser preservá-las no Cloud Chat, veja abaixo o que entregar pra gente. O que você precisa nos entregar 1. Caixa de entrada pronta. Garanta que a migração do seu canal está concluída e a inbox está criada e ativa no Cloud Chat — só importamos o histórico depois disso (sem inbox, não há para onde importar). 2. O histórico no formato JSON. Exporte suas conversas antigas em um arquivo JSON com a chave conversations_data — uma lista de tickets. Cada ticket tem: - Datas do ticket: created_at (abertura) e updated_at (última atualização), em ISO 8601 (ex.: 2024-01-15T10:30:00Z). - contact: identifier (obrigatório, único e estável por cliente) e, opcionais, name, email, phone_number (E.164). - messages: cada mensagem com content (texto), message_type (incoming = cliente, outgoing = agente, activity = nota interna), created_at (ISO 8601) e private (true para nota interna). - custom_attributes (recomendado): as informações que você quer preservar como referência. Guarde o ID do ticket antigo em external_helpdesk_id (rastreabilidade), e inclua as tags e atributos do ticket que quiser manter (ex.: priority, source_queue, tags). Essas tags entram como informação/etiqueta de referência na conversa importada — não como a tag nativa que filtra na plataforma. Nos diga quais quer preservar. Exemplo: { "conversations_data": [ { "contact": { "identifier": "user_6782902", "name": "John Doe", "email": "[email protected]", "phone_number": "+5511988887777" }, "custom_attributes": { "external_helpdesk_id": "ZD-78901", "priority": "high" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-16T14:22:00Z", "messages": [ { "content": "Meu pedido não chegou.", "message_type": "incoming", "created_at": "2024-01-15T10:30:00Z", "private": false }, { "content": "Oi! Já verifiquei, sai hoje.", "message_type": "outgoing", "created_at": "2024-01-15T10:31:00Z", "private": false }, { "content": "Cliente VIP, priorizar.", "message_type": "activity", "created_at": "2024-01-15T11:16:00Z", "private": true } ] } ] } 3. Combine o escopo com seu contato. Alinhe com a gente o período (todo o histórico ou um recorte, ex.: últimos 12 meses), quais tags/atributos quer preservar, e se quer separar por canal (WhatsApp, Instagram, e-mail…). 4. Envie o arquivo. Suba o(s) arquivo(s) .json na pasta do Google Drive que a gente compartilha com você — ou, se preferir, mande um link do arquivo (Google Drive, OneDrive, o que for). Se você quer manter os canais separados, envie um arquivo por canal (ex.: historico_whatsapp.json). 5. Comece por uma amostra. Antes do arquivo completo, mande 20–50 tickets no formato — a gente importa num ambiente de validação, você confere, e só então processamos tudo. :::info Não é importado: imagens e anexos. A migração é de texto (mensagens, notas internas e metadados). Se um anexo era essencial, inclua o link dele no texto da mensagem. Regras: datas sempre em ISO 8601 (se não conseguir em UTC, nos avise o fuso); identifier único de verdade (dois clientes com o mesmo valor viram um só); arquivo em UTF-8. ::: A Cloud Humans faz a importação pra você Com o arquivo enviado, o time da Cloud Humans executa a importação — importamos em lotes, respeitando os limites da plataforma, e confirmamos o resultado com você. Você não precisa mexer em API nem nos dar acesso à sua ferramenta antiga. Prefere fazer por conta própria? Segue o passo a passo Se seu time tem desenvolvedor e prefere rodar a importação, use a API. Além do arquivo no formato acima, você vai precisar de: API Key (ver Como pegar a sua API Key), CLOUDCHAT_DOMAIN, ACCOUNT_ID e INBOX_ID. Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Seu token de API | O corpo é o mesmo conversations_data descrito acima. Limites — cada requisição aceita no máximo 10.000 tickets ou 15 MB. Para volumes maiores, particione em múltiplas requisições. O identifier do contato é único (dedup). Para os custom_attributes aparecerem formatados no painel, defina-os antes em Settings → Custom Attributes (escopo: Conversation). Onde encontrar os IDs CLOUDCHAT_DOMAIN Parte da URL ao fazer login na sua conta: ACCOUNT_ID Em Configurações da conta: API_TOKEN Em https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings: INBOX_ID ID da caixa que receberá os tickets. Pode ser obtido na URL da aba de configurações da inbox: Observações - Para criar tickets novos via API (não importação histórica): Como criar tickets via API no Cloud Chat - Para importar contatos antes ou junto com a importação de tickets: Como importar contatos em massa via API - Visão geral das APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Última actualización el Sep 15, 2026

API: Importación masiva de contactos vía API

Cloud Chat: Importación masiva de contactos vía API Para importar o actualizar varios contactos a la vez vía API en Cloud Chat, envía una solicitud POST al endpoint a continuación. ¿Quieres importar solo un contacto? Usa el endpoint de Importar contacto individual. Los dos endpoints tienen formatos de cuerpo diferentes — no los mezcles. Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/bulk_create Encabezados | Encabezado | Valor | | --- | --- | | content-type | application/json | | api_access_token | Tu token de API | Cuerpo de la Solicitud El cuerpo usa un arreglo data que contiene los contactos a importar: { "upsert": true, "data": [ { "name": "Contacto 1", "email": "[email protected]", "phone_number": "+5511999998888", "identifier": "EXT-001", "additional_attributes": { "company": "Acme", "city": "São Paulo" }, "custom_attributes": { "plano": "premium", "origen": "campaña-marzo" } }, { "name": "Contacto 2", "phone_number": "+5511888887777" } ] } Campos por contacto | Campo | Obligatorio | Descripción | | --- | --- | --- | | phone_number | Al menos 1 de los 3* | Teléfono en formato internacional con + | | email | Al menos 1 de los 3* | Correo electrónico del contacto | | identifier | Al menos 1 de los 3* | Identificador externo único | | name | No | Nombre del contacto | | additional_attributes | No | Objeto con atributos adicionales (clave-valor). Sobrescrito por completo en cada update (salvo que se use merge_jsonb: "shallow", ver más abajo). | | custom_attributes | No | Objeto con atributos personalizados creados por la cuenta (clave-valor). Sobrescrito por completo en cada update (salvo que se use merge_jsonb: "shallow", ver más abajo). | | tags_add | No | Lista de etiquetas a agregar. Requiere apply_tags: true o api_version: "v2". | | tags_remove | No | Lista de etiquetas a remover. Requiere apply_tags: true o api_version: "v2". | *Cada contacto debe tener al menos uno entre phone_number, email o identifier. Bandera upsert | Valor | Comportamiento | | --- | --- | | false o ausente | Solo crea contactos nuevos. Si alguno de los campos clave (email, teléfono o identifier) ya existe en la base, la fila falla con error 422 (no se ignora silenciosamente). | | true | Crea contactos nuevos y actualiza contactos existentes. | Ejemplo de solicitud (curl) curl -X POST \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/bulk_create' \ --header 'content-type: application/json' \ --header 'api_access_token: TU_TOKEN' \ --data '{ "upsert": true, "data": [ { "name": "Contacto 1", "email": "[email protected]", "phone_number": "+5511999998888" }, { "name": "Contacto 2", "phone_number": "+5511888887777" } ] }' Respuesta Éxito (HTTP 201) { "success": true } Error de validación o conflicto (HTTP 422) { "success": false, "errors": [ { "index": 0, "attributes": { "name": "Contacto 1", "email": "[email protected]", ... }, "errors": ["Email is invalid"] }, { "index": 1, "attributes": { "name": "Contacto 2", ... }, "errors": "Duplicate: Contact with this phone number already exists" } ] } - index indica la posición (0-based) de la fila en el array data. - errors por fila puede ser un array de mensajes de validación O un único string para conflictos de clave (duplicidad, divergencia identifier × email × phone — en este último caso el código devuelto es AMBIGUOUS_MATCH). Cuerpo vacío (HTTP 400) Devuelto cuando data es nulo o un array vacío. Precauciones con upsert Atención — riesgo de pérdida de datos con upsert: true: Al actualizar un contacto existente vía bulk_create con upsert: true, cualquier campo que no envíes será sobrescrito con null. Ejemplo: Si un contacto tiene email y phone_number registrados, y envías una actualización solo con phone_number, el campo email será eliminado. Si necesitas actualizar solo algunos campos sin borrar los demás, usa el endpoint de actualización individual: PUT /api/v1/accounts/{{ACCOUNT_ID}}/contacts/{{CONTACT_ID}} Otra alternativa es usar coalesce_nulls: true (ver sección "Comportamiento avanzado") para que los null enviados se interpreten como "preservar el valor existente". Comportamiento avanzado (opcional) A partir del 30 de abril de 2026, el endpoint acepta parámetros opcionales en el cuerpo de la solicitud que permiten ajustar cómo se procesa el payload. Estos parámetros son opt-in: si no los envías, el comportamiento es el de antes del 30/04/2026. | Parámetro | Tipo | Default | Efecto | | --- | --- | --- | --- | | api_version | string | "v1" | "v1": paridad con el comportamiento anterior. "v2": habilita todas las features nuevas en bloque (tags granulares, __DELETE__, merge JSONB shallow, lookup por variantes). "v2-safe": subconjunto conservador. | | apply_tags | boolean | false | Habilita el procesamiento de tags_add / tags_remove por fila. | | respect_sentinel | boolean | false | Habilita la semántica del valor __DELETE__ para borrar claves de JSONB y campos escalares. | | merge_jsonb | string | "overwrite" | "overwrite": sobrescribe el objeto JSONB completo. "shallow": hace merge clave por clave (no sobrescribe lo que no envíes). | | coalesce_nulls | boolean | false | Trata null en el payload como "preservar valor existente" en lugar de "borrar". | | coerce_blank_jsonb | boolean | false | Trata cadena vacía ("") en valores de JSONB como __DELETE__ (borra la clave). | | normalize_lookup | boolean | false | Habilita la búsqueda por variantes de teléfono (especialmente útil para números BR con/sin el dígito 9). | | orphan_guard | boolean | false | Rechaza el payload cuando la actualización dejaría a un contacto existente sin ninguna clave fuerte (email, teléfono, identifier). | Atajo: para habilitar todas las features nuevas en bloque sin tener que activar cada flag por separado, usa api_version: "v2". tags_add y tags_remove (granulares) Permite agregar y remover etiquetas específicas sin sobrescribir las existentes en el contacto: { "api_version": "v2", "data": [ { "email": "[email protected]", "tags_add": ["vip", "premium"], "tags_remove": ["pending"] } ] } ⚠️ Atención: tags_add y tags_remove son silenciosamente ignorados si no envías apply_tags: true o api_version: "v2". El default mantiene el comportamiento anterior. Si en la misma fila una etiqueta aparece en tags_add y en tags_remove, la remoción gana (el orden de la operación es agregar → remover). __DELETE__ para borrar claves en JSONB Con respect_sentinel: true o api_version: "v2", el valor literal "__DELETE__" borra la clave correspondiente: { "api_version": "v2", "data": [ { "email": "[email protected]", "custom_attributes": { "favorite_color": "__DELETE__" } } ] } El sentinel funciona en claves de primer nivel de additional_attributes y custom_attributes. También funciona en campos escalares (name, phone_number, email, identifier) para limpiar el valor (NULL). merge_jsonb: shallow vs overwrite Por defecto ("overwrite"), enviar un custom_attributes reemplaza el objeto completo. Con "shallow", solo se actualizan las claves presentes en el payload, preservando las demás: { "api_version": "v1", "merge_jsonb": "shallow", "respect_sentinel": true, "data": [ { "email": "[email protected]", "custom_attributes": { "plano": "gold" } } ] } ⚠️ Atención — combinación arriesgada: usar merge_jsonb: "shallow" sin respect_sentinel: true significa que no hay forma de borrar una clave durante el merge. Si tu integración asume que enviar una cadena vacía o ausente debería eliminar la clave, esa expectativa no se cumplirá: el valor antiguo permanecerá intacto. Cuando uses shallow, activa también respect_sentinel: true y usa "__DELETE__" para borrar claves explícitamente. coalesce_nulls Por defecto, enviar "email": null borra el campo. Con coalesce_nulls: true, los null se ignoran y el valor existente se conserva: { "coalesce_nulls": true, "data": [ { "phone_number": "+5511999998888", "email": null, "name": "Nuevo nombre" } ] } coerce_blank_jsonb Trata cadenas vacías dentro de JSONB como instrucción de borrado (equivalente a __DELETE__): { "coerce_blank_jsonb": true, "respect_sentinel": true, "data": [ { "email": "[email protected]", "custom_attributes": { "nota_interna": "" } } ] } ⚠️ Atención — riesgo de borrado accidental: no actives coerce_blank_jsonb: true si tu integración envía cadenas vacías legítimas en JSONB (por ejemplo, un campo que el cliente dejó en blanco intencionalmente y debe persistirse como ""). Con esta bandera activa, cualquier "" será interpretado como "borra esta clave". Úsalo solo si controlas el origen del payload y sabes que las cadenas vacías representan eliminación. normalize_lookup — búsqueda por variantes de teléfono Con normalize_lookup: true o api_version: "v2", al buscar el contacto existente el sistema considera variantes del número de teléfono (especialmente para números brasileños con o sin el dígito 9): { "normalize_lookup": true, "data": [ { "phone_number": "+5511933334444", "name": "María" } ] } Si en la base ya existe un contacto con +551133334444 (sin el 9), el sistema lo encuentra y lo actualiza, en lugar de crear un duplicado. Útil para evitar duplicación cruzada entre formatos. orphan_guard Con orphan_guard: true, el sistema rechaza cualquier fila cuyo resultado dejaría al contacto sin ninguna clave fuerte (sin email, sin teléfono y sin identifier): { "orphan_guard": true, "data": [ { "identifier": "EXT-001", "email": "__DELETE__", "phone_number": "__DELETE__" } ] } ⚠️ Atención: las cuentas que tienen contactos creados con solo identifier (sin email ni teléfono) deben evaluar antes de activar este flag. Esos contactos pueden ser rechazados al actualizarse si la lógica de tu integración asume que identifier solo no es suficiente. Usa orphan_guard: true solo si sabes que todos tus contactos tienen al menos una clave fuerte (email o teléfono) además del identifier, o si ese es exactamente el comportamiento que deseas hacer cumplir. Diferencia entre este endpoint y la Importación individual | | Este endpoint (bulk_create) | Importar individual (external_import) | | --- | --- | --- | | Cuándo usar | Importar/actualizar varios contactos a la vez | Importar/actualizar 1 contacto por llamada | | Formato del cuerpo | {"upsert": true, "data": [{...}, {...}]} | Objeto JSON simple (plano) | | Upsert | Necesita el banderín "upsert": true | Siempre activo (automático) | | Precaución con null | Campos omitidos se sobrescriben con null (salvo con coalesce_nulls: true) | Campos omitidos se conservan | | Búsqueda por variantes de teléfono | Disponible con normalize_lookup: true o api_version: "v2" | No disponible (solo lookup exacto por phone_number) | ¡No mezcles los formatos! Si envías un objeto plano (sin data: [...]) a este endpoint, no funcionará. Para contacto individual, usa el endpoint de importación individual. Dónde encontrar los parámetros de configuración - CLOUDCHAT_DOMAIN: El dominio visible en la URL del navegador al acceder a Cloud Chat - ACCOUNT_ID: En configuraciones de la cuenta - API_TOKEN: En https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings

Última actualización el Sep 22, 2026

Cómo enviar un mensaje proactivo por WhatsApp vía API

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. Si este artículo y la referencia no coinciden, vale lo que dice la referencia. ::: Cuándo usar - Quieres iniciar una conversación de WhatsApp por API desde un sistema externo - Necesitas disparar plantillas aprobadas por Meta con variables dinámicas - Necesitas entender el comportamiento esperado del ticket creado por esta API Requisitos previos - WhatsApp ya conectado a Cloud Chat con un inbox_id válido — ver Guía Maestra — Cómo conectar tu número de WhatsApp a Cloud Chat - Plantilla aprobada por Meta registrada en Cloud Chat — ver Cómo crear, editar y eliminar plantillas de WhatsApp en Cloud Chat - API Key a la mano — ver Cómo encontrar tu API Key en Cloud Chat - Número de teléfono del destinatario en formato E.164 (ej.: +5511999998888) Sobre este artículo Este endpoint crea una conversación proactiva por WhatsApp usando una plantilla previamente configurada. Los parámetros de la plantilla son dinámicos y varían según la configuración de la plantilla. Comportamiento de creación del ticket :::info Como el sistema no sabe qué agente debe recibirlo, el mensaje no nace asignado. Por eso el globo aparece verde (mensajes automáticos), en lugar de naranja. ::: - Genera un nuevo ticket — excepto si la bandeja está configurada con conversación única (lock to single conversation), en cuyo caso el mensaje se agrega a la conversación existente del contacto - El ticket nace con estado abierto :::warning Si el cliente tiene dos tickets abiertos, los nuevos mensajes enviados por el cliente siempre se dirigirán al ticket más reciente. ::: Endpoint POST https://cloudchat.cloudhumans.com/api/v1/accounts/{account_id}/conversations/create_proactive_whatsapp_conversation Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Clave de acceso de la API | Parámetros del body | Parámetro | Obligatorio | Descripción | | --- | --- | --- | | inbox_id | Sí | ID de la bandeja por la que se enviará el mensaje | | phone_number | Sí | Número del destinatario en formato E.164 | | template_name | Sí | Nombre exacto de la plantilla aprobada | | labels | No | Array de strings con etiquetas a aplicar a la conversación creada — ver la sección Aplicando etiquetas (labels) abajo | | header_attachment | No | URL del adjunto, si la plantilla admite multimedia en el encabezado | | button_param_# | No | Variables de botones — reemplaza # por el índice (0 a N) | | Variables de la plantilla | Sí, si la plantilla tiene variables | Un campo para cada variable, con su nombre exacto, en la raíz del JSON (ver abajo) | Sobre las variables dinámicas Cada variable de la plantilla se convierte en un campo en la raíz del JSON, junto a inbox_id, phone_number y template_name, con el nombre exacto de la variable: - Plantilla con variables con nombre, como Hola {{cliente}}, tu factura de {{monto}} vence mañana: envía los campos "cliente" y "monto". - Plantilla con variables numeradas, como Hola {{1}}, tu factura de {{2}} vence mañana: envía los campos "1" y "2". Si falta alguna variable, la API rechaza la solicitud con el error missing params. Los campos que no corresponden a ninguna variable se ignoran. Los nombres de variable con punto o tilde (como {{contact.name}} o {{horário}}) no son aceptados por Meta como variable. Ejemplo de solicitud curl --location 'https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/create_proactive_whatsapp_conversation' \ --header 'content-type: application/json' \ --header 'api_access_token: ACCESS_TOKEN' \ --data '{ "inbox_id": "INBOX_ID", "phone_number": "+5511999998888", "template_name": "recordatorio_pago", "labels": ["campana-x", "vip"], "header_attachment": "ATTACHMENT_URL", "button_param_0": "BUTTON PARAMETER", "button_param_1": "ANOTHER BUTTON PARAMETER", "cliente": "Juan", "monto": "$120.00" }' Dónde encontrar los parámetros - account_id — en el panel administrativo de la cuenta - inbox_id — ID de la bandeja de entrada configurada (https://cloudchat.cloudhumans.com/app/accounts/{account_id}/settings/inboxes/{inbox_id}) - api_access_token — genéralo en el panel de configuración de API - Variables dinámicas — consulta la configuración de la plantilla en el panel administrativo. Estos parámetros van en la raíz del payload. :::warning Asegúrate de que el número de teléfono esté en formato E.164, con el código de país. ::: Aplicando etiquetas (labels) a la conversación creada El parámetro opcional labels recibe un array de strings con los títulos de las etiquetas a aplicar a la conversación creada por el disparo — sin necesidad de una segunda llamada a la API de labels. "labels": ["campana-x", "vip"] Comportamiento: - Los títulos se normalizan: se eliminan los espacios en los extremos, se convierten a minúsculas y se deduplican. - Las etiquetas se agregan a la conversación (nunca reemplazan etiquetas existentes) — en bandejas con conversación única, las etiquetas de disparos anteriores y las aplicadas por agentes se preservan. - Si la etiqueta todavía no existe en la cuenta, se crea automáticamente (y comienza a aparecer en los filtros del panel) — siempre que el token utilizado sea de un administrador o CX Engineer. Con token de agente (no admin), solo se aplican etiquetas ya existentes en la cuenta; los títulos nuevos se ignoran silenciosamente. - Omitir el parámetro (o enviar un array vacío) mantiene el comportamiento anterior — no se aplica ninguna etiqueta. Límite de solicitudes (rate limit) Este endpoint acepta como máximo 200 solicitudes por minuto. Por encima de ese límite, la API responde HTTP 429 y la solicitud no se procesa (el mensaje no se envía). La respuesta incluye los siguientes headers: | Header | Descripción | | --- | --- | | Retry-After | Segundos hasta que la ventana permita nuevas solicitudes | | X-RateLimit-Limit | Límite de solicitudes de la ventana (200) | | X-RateLimit-Remaining | Solicitudes restantes en la ventana actual | Ejemplo de respuesta al exceder el límite: { "error": "Rate limit exceeded. Retry later.", "retry_after": 42 } :::warning Si tu integración dispara mensajes en lote, maneja la respuesta 429 reenviando la solicitud después del tiempo indicado en Retry-After. Sin este manejo, los envíos que excedan el límite se perderán. ::: Observaciones - Para integrar este endpoint con workflows de HubSpot: Cómo enviar un mensaje proactivo por WhatsApp vía HubSpot - Para entender qué APIs están disponibles en Cloud Chat: Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API - Para evitar bloqueos y cuidar la reputación del número: Cómo evitar bloqueos y baneos en WhatsApp

Última actualización el Sep 23, 2026

API: Enviar Mensaje Proactivo por WhatsApp mediante integración con Hubspot

Envío de mensajes proactivos en disparos de webhook vía hubspot Utilizando nuestro endpoint de envíos proactivos, es posible iniciar conversaciones por WhatsApp através de webhooks integrados a Hubspot. Estos webhooks pueden alimentarse con la base de datos de información de Hubspot, haciendo que el mensaje sea dinámico en contexto. 📌 ¿Cuándo usar esta integración? Utiliza este flujo cuando desees: - Enviar automáticamente un mensaje por WhatsApp (utilizando una plantilla aprobada por Meta) desde Cloud Chat tras una acción en HubSpot - Personalizar el mensaje con propiedades del contacto en HubSpot (nombre, número de pedido, estado, entre otros) - Crear flujos automáticos de seguimiento, cobranza, incorporación o actualización de estado ✅ Requisitos previos Antes de configurar el endpoint, necesitas: - Tener el número de WhatsApp conectado a Cloud Chat y poseer el inbox_id de la bandeja de entrada correspondiente. Consulta la FAQ: Guía maestra — Cómo conectar tu número de WhatsApp a Cloud Chat El inbox_id se puede encontrar accediendo a la configuración de la bandeja de entrada en Cloud Chat. La URL seguirá el siguiente patrón: https://cloudchat.cloudhumans.com/app/accounts/{{account_id}}/settings/inboxes/{{inbox_id}} - Tener una plantilla aprobada en Meta registrada en Cloud Chat. Accede a la FAQ: Cómo crear plantillas de WhatsApp en Cloud Chat (creación, edición y aprobación). - Tener tu API Key de Cloud Chat a mano. Accede a la FAQ siguiente para obtener la clave y el token: API: Enviar mensaje proactivo por WhatsApp. Paso 1: Crear el Workflow en HubSpot Para crear un webhook de disparo proactivo en un workflow de Hubspot, sigue los siguientes pasos. En la barra lateral principal de Hubspot, pasa el mouse sobre el símbolo de automatizaciones y luego haz clic en Flujos de trabajo para ser redirigido al panel de control de workflows: Al entrar al panel, haz clic en Crear flujo de trabajo y luego selecciona la opción Desde cero: Elige las opciones que dispararán este trigger: Paso 2: Configurar el envío del Webhook Con la configuración inicial del workflow completada, ahora debemos construir el payload que se enviará en el webhook. Para iniciar la configuración del webhook, haz clic en el botón de añadir acción (+): En el panel izquierdo, haz clic en Operaciones de datos y luego selecciona Enviar un webhook: En el selector de método, elige la opción POST: Luego, completa la información de url del webhook y la clave API: URL: https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_whatsapp_conversation Para configurar la Clave API, haz clic en Añadir secreto. Luego, aparecerá una ventana solicitando el Nombre del secreto y el Valor del secreto. Ingresa en Nombre del Secreto api_access_token y en el campo Valor del Secreto, la API Key de Cloud Chat que guardaste previamente. Estructura del Payload Por último, completa el body (payload) de la solicitud para realizar el disparo, incluyendo: - template_name (requerido) — valor estático que corresponde exactamente al nombre de la plantilla aprobada en Cloud Chat. - inbox_id (requerido) — valor estático que identifica la bandeja de entrada de envío en Cloud Chat. - phone_number (requerido) — campo dinámico usando la variable de HubSpot {{contact.phone}}. - Variables de la plantilla — Al registrar la plantilla en Cloud Chat, las variables configuradas en ella deben tener exactamente el mismo nombre que las propiedades enviadas por HubSpot en el payload. Esto significa que el nombre de la variable en la plantilla debe ser idéntico al nombre del campo enviado en el webhook (respetando mayúsculas/minúsculas y guiones bajos), para que la sustitución de valores sea correcta en el momento del disparo. Aquí tienes un ejemplo de payload: Nota: Las variables usadas arriba, así como la información sobre la url del webhook y la clave API, son discutidas en la sección de envíos proactivos vía API.

Última actualización el Sep 22, 2026

Cómo extraer datos por lotes vía API (Data Extract API)

:::warning Aviso importante: esta API no seguirá evolucionando. La forma recomendada hoy para la extracción masiva de datos es la nueva documentación: CloudHumans Data Export. ::: Cuándo usarla - Necesitas exportar datos históricos de tickets para BI, auditoría o un dashboard externo - Quieres alimentar informes personalizados con datos completos de Cloud Chat - Necesitas rastrear eventos de entrega de campañas y envíos proactivos Requisitos previos - API Key generada por un usuario administrador o supervisor — ver Cómo obtener tu API Key en Cloud Chat - CLOUDCHAT_DOMAIN y ACCOUNT_ID - Período de extracción de máximo 5 días (120 horas) por solicitud :::warning Esta API está destinada exclusivamente a la extracción histórica por lotes. Para consultas en tiempo real o acciones sobre tickets, usa las otras APIs de la Guía Maestra. ::: Sobre este artículo La Data Extract API permite exportar datos completos de tus tickets directamente desde tu cuenta en Cloud Chat — fechas, estados, responsables, tiempos de respuesta y mucho más. Ideal para informes personalizados e integraciones externas. Solicitud base curl --location 'https://{CLOUDCHAT_DOMAIN}/api/v2/accounts/{ACCOUNT_ID}/data_extracts?startDate=2025-03-27T01:58:59&endDate=2025-03-28T01:59:00&type=BASE_TICKET_METRICS' \ --header 'Accept: application/json' \ --header 'api_access_token: {API_TOKEN}' Dónde encontrar los parámetros - CLOUDCHAT_DOMAIN — parte de la URL al iniciar sesión en tu cuenta - ACCOUNT_ID — después de iniciar sesión, el ID aparece en la URL como app/accounts/{id}/dashboard. Ej.: en cloudhumans.com/app/accounts/1/conversations/6341 el account_id es 1 - API_TOKEN — genéralo desde un perfil administrador o supervisor (en "Configurações do perfil" (Configuración del perfil), en tu propio entorno — usa el dominio de tu cuenta, ej.: https://TU-DOMINIO.cloudhumans.com/app/accounts/{ACCOUNT_ID}/profile/settings. El dominio varía según la instancia: cloudchat, cloudchat2, cloudchat3…) Parámetros obligatorios - startDate — Fecha y hora de inicio (UTC) en el formato yyyy-MM-ddTHH:mm:ss. Ej.: 2025-03-27T01:58:59 - endDate — Fecha y hora de término (UTC). Debe ser posterior a startDate y el intervalo no puede superar 5 días (120 horas). Ej.: 2025-03-28T01:59:00 - type — Tipo de datos a exportar (ver la lista abajo) - account_id — ID de la cuenta, indicado en la ruta de la URL Tipos disponibles - BASE_TICKET_METRICS - TICKET_METRICS_WITH_AGENT_INFORMATION - TICKET_SUMMARY - CAMPAIGN_DELIVERY_EVENTS - SINGLE_CONTACT_DELIVERY_EVENTS Parámetro opcional: rangeFilterProperty Define qué campo de fecha se usa para aplicar los filtros de período. | Valor | Comportamiento | | --- | --- | | CREATED_AT (predeterminado) | Filtra por la fecha de creación | | UPDATED_AT | Filtra por la fecha de la última actualización | Intervalo de fechas :::info Para garantizar estabilidad y rendimiento, el intervalo máximo permitido por solicitud es de 5 días. Para exportar períodos mayores (ej.: 30 días), divídelo en varias solicitudes — 6 llamadas consecutivas con ventanas de 5 días cubren un mes entero. ::: Límite de solicitudes (rate limit) La Data Extract API aplica un límite de 20 solicitudes por minuto por token. Tokens distintos de la misma cuenta tienen presupuestos independientes. Qué pasa al superar el límite Las solicitudes que superan el límite reciben HTTP 429 Too Many Requests: { "error": "Rate limit exceeded. Retry later.", "retry_after": 42 } Recomendaciones :::warning - Respeta el encabezado Retry-After antes de intentar de nuevo. Los bucles de reintento sin backoff amplifican el bloqueo - Para extracciones grandes (ej.: 30 días), combina ventanas de 5 días con espaciado entre solicitudes — 20/min es holgado para el volumen típico - Si tu integración necesita mayor throughput de forma sostenida, contacta al soporte ::: 1. BASE_TICKET_METRICS Devuelve datos básicos de los tickets. Campos devueltos: | Campo | Tipo | Descripción | Dato Posiblemente Sensible | | --- | --- | --- | --- | | ticketId | Entero | ID interno del ticket | No | | displayTicketId | Entero | ID mostrado al usuario en Cloud Chat — visible en la URL y en la búsqueda por filtros | No | | inboxId | Entero | ID de la bandeja de entrada | No | | accountId | Entero | ID de la cuenta | No | | accountName | Texto | Nombre de la cuenta | No | | ticketStatus | Texto | Estado del ticket: open (Abierto), resolved (Resuelto), pending (Pendiente), snoozed (Aplazado) | No | | teamName | Texto | Nombre del equipo responsable | No | | ticketPriorityName | Texto | Prioridad: low, medium, high, urgent | No | | ticketType | Texto | Tipo del ticket (primera etiqueta asociada) | No | | inboxName | Texto | Nombre de la bandeja de entrada | No | | ticketTitle | Texto | Título del ticket — puede contener el nombre o el teléfono del contacto | Sí | | channel | Texto | Canal de comunicación (ej.: Whatsapp) | No | | tags | Texto | Etiquetas del ticket separadas por comas | No | | createdAt | Timestamp | Fecha y hora de creación del ticket | No | | firstReplyAt | Timestamp | Fecha y hora de la primera respuesta | No | | firstReplyTime | Decimal | Tiempo hasta la primera respuesta (en minutos) | No | | resolvedAt | Timestamp | Fecha y hora de resolución | No | | totalResolutionTimeMin | Decimal | Tiempo total de resolución (en minutos) | No | | agentId | Entero | ID del agente responsable | No | | ticketOwner | Texto | Nombre del agente responsable | Sí | | ticketOwnerEmail | Texto | Correo electrónico del agente responsable | Sí | | contactId | Entero | ID del contacto | No | | contactName | Texto | Nombre del contacto | Sí | | contactEmail | Texto | Correo electrónico del contacto | Sí | | contactPhone | Texto | Teléfono del contacto | Sí | | campaignId | Entero | ID de la campaña que originó el ticket, si aplica | No | | proactivelyInitiated | Booleano | Indica si el ticket se inició de forma proactiva | No | :::warning Al configurar la zona horaria de la cuenta (ej.: GMT-3), los campos de tipo timestamp (createdAt, firstAgentAssignmentTime, firstReplyAt, firstAgentFirstReplyTime, resolvedAt, firstReplyTime, firstReplierAgentAssignmentTime, firstReplierAgentFirstReplyTime, repliedAt, readAt, receivedAt, sentAt) se devuelven en la zona configurada. Sin zona horaria configurada, los horarios vienen en UTC. Configuración: Configuración de zona horaria. ::: Ejemplo de respuesta [ { "ticketId": 123456, "displayTicketId": 7890, "inboxId": 101, "accountId": 42, "accountName": "Minha Empresa", "ticketStatus": "resolved", "teamName": "Meu Time", "ticketPriorityName": "High", "ticketType": "suporte", "inboxName": "WhatsApp", "ticketTitle": "+5511999999999", "channel": "Whatsapp", "createdAt": "2025-03-27T09:53:14.791Z", "firstReplyAt": "2025-03-27T10:09:29.225Z", "firstReplyTime": 16.24, "resolvedAt": "2025-03-27T13:20:15.830Z", "totalResolutionTimeMin": 207.01, "tags": "suporte,prioridade_alta", "agentId": 42, "ticketOwner": "ClaudIA", "ticketOwnerEmail": "[email protected]", "contactId": 998877, "contactName": "Contact Name", "contactEmail": "[email protected]", "contactPhone": "+5511887774411", "campaignId": 123, "proactivelyInitiated": true } ] 2. TICKET_METRICS_WITH_AGENT_INFORMATION Incluye detalles sobre el agente que respondió y resolvió. Campos adicionales: | Campo | Tipo | Descripción | Dato Posiblemente Sensible | | --- | --- | --- | --- | | ticketLink | Texto | URL directa al ticket en Cloud Chat | No | | agentOnResolutionId | Entero | ID del agente humano que resolvió el ticket | No | | agentOnResolutionName | Texto | Nombre del agente humano que lo resolvió | Sí | | agentOnResolutionEmail | Texto | Correo electrónico del agente humano que lo resolvió | Sí | | firstAgentReplyId | Entero | ID del primer agente humano que respondió | No | | firstAgentReplyName | Texto | Nombre del primer agente humano que respondió | Sí | | firstAgentReplyEmail | Texto | Correo electrónico del primer agente humano que respondió | Sí | | firstAgentAssignmentTime | Timestamp | Fecha y hora en que el ticket fue asignado al primer agente | No | | firstAgentFirstReplyTime | Timestamp | Fecha y hora de la primera respuesta del agente | No | | firstReplierAgentAssignmentTime | Timestamp | Fecha y hora de asignación del agente que respondió primero | No | | firstReplierAgentFirstReplyTime | Timestamp | Timestamp de la primera respuesta del agente que respondió primero | No | | firstAgentReplyTimeMin | Decimal | Tiempo entre la asignación y la primera respuesta del agente (min) | No | | firstAgentResolutionTimeMin | Decimal | Tiempo entre la asignación y la resolución del ticket (min) | No | | csatScore | Numérico | Nota de satisfacción (CSAT) otorgada por el cliente | No | | csatFeedback | Texto | Comentario textual dejado por el cliente en la encuesta CSAT | Sí | | contactCustomFields | JSON | Campos personalizados del contacto — pueden contener datos personales | Sí | | conversationCustomFields | JSON | Campos personalizados de la conversación — pueden contener datos personales | Sí | | conversationAdditionalFields | JSON | Metadatos adicionales de la conversación — pueden contener datos personales | Sí | Ejemplo de respuesta [ { "ticketId": 11111, "displayTicketId": 11111, "accountName": "account name", "inboxName": "WhatsApp", "ticketLink": "https://cloudchat.cloudhumans.com/app/accounts/99999/conversations/11111", "ticketStatus": "resolved", "createdAt": "2025-03-27T13:00:40.897954", "resolvedAt": "2025-03-27T15:38:02.743726", "agentOnResolutionId": 225, "agentOnResolutionName": "ClaudIA", "agentOnResolutionEmail": "[email protected]", "firstAgentReplyId": 111, "firstAgentReplyName": "ClaudIA", "firstAgentReplyEmail": "[email protected]", "firstAgentAssignmentTime": "2025-03-27T13:16:13.001269", "firstAgentFirstReplyTime": "2025-03-27T13:17:01.344971", "firstAgentReplyTimeMin": 0.81, "firstAgentResolutionTimeMin": 141.83, "csatScore": null, "csatFeedback": "", "contactCustomFields": "{}", "conversationCustomFields": "{}", "conversationAdditionalFields": "{}" } ] :::info - firstAgentReplyTimeMin — tiempo entre firstAgentAssignmentTime y firstAgentFirstReplyTime - firstAgentResolutionTimeMin — tiempo entre firstAgentAssignmentTime y resolvedAt ::: 3. TICKET_SUMMARY Devuelve un resumen de la conversación del ticket. Campos devueltos: | Campo | Tipo | Descripción | Dato Posiblemente Sensible | | --- | --- | --- | --- | | ticketId | Entero | ID interno del ticket | No | | displayTicketId | Entero | ID mostrado al usuario en Cloud Chat — visible en la URL y en la búsqueda por filtros | No | | ticketLink | Texto | URL directa al ticket en Cloud Chat | No | | summary | Texto | Resumen de la conversación entre el cliente y el agente — puede venir truncado en conversaciones largas | Sí | [ { "ticketId": 1111, "displayTicketId": 1111, "ticketLink": "https://cloudchat.cloudhumans.com/app/accounts/99999/conversations/1111", "summary": "CONTATO: Oi\nUSUÁRIO: Olá!" } ] :::warning El campo summary no garantiza la transcripción íntegra de la conversación: consolida fragmentos y, en conversaciones largas, el contenido puede venir cortado. Si necesitas el historial completo, usa el envío de la transcripción por correo electrónico desde la propia conversación, en lugar de la API. ::: 4. CAMPAIGN_DELIVERY_EVENTS Devuelve eventos de entrega de campañas de WhatsApp, rastreando por contacto y campaña el estado de los mensajes. Campos devueltos: | Campo | Tipo | Descripción | Dato Posiblemente Sensible | | --- | --- | --- | --- | | id | Entero | ID único del evento de entrega | No | | campaignId | Entero | ID de la campaña | No | | campaignTitle | Texto | Título de la campaña | No | | audience | Texto | Audiencia/lista utilizada en la campaña | No | | contactId | Entero | ID del contacto destinatario | No | | contactName | Texto | Nombre del contacto destinatario | Sí | | contactEmail | Texto | Correo electrónico del contacto destinatario | Sí | | contactPhoneNumber | Texto | Teléfono del contacto destinatario | Sí | | ticketId | Entero | ID del ticket generado por el envío, si lo hay | No | | displayTicketId | Texto | ID mostrado al usuario en Cloud Chat — visible en la URL y en la búsqueda por filtros | No | | messageSent | Booleano | Flag que indica si el mensaje fue enviado a la API de WhatsApp (Meta) | No | | sentAt | Timestamp | Fecha y hora del envío | No | | messageReceived | Booleano | Flag que indica si el mensaje fue entregado al dispositivo del contacto | No | | receivedAt | Timestamp | Fecha y hora de la entrega | No | | messageRead | Booleano | Flag que indica si el mensaje fue leído (depende de la configuración de privacidad del contacto) | No | | readAt | Timestamp | Fecha y hora de la lectura | No | | messageReplied | Booleano | Flag que indica si el mensaje fue respondido | No | | repliedAt | Timestamp | Fecha y hora de la primera respuesta | No | | error | Texto | Error de entrega: número inválido, sin WhatsApp, bloqueo, etc. | No | | createdAt | Timestamp | Fecha y hora de creación del registro | No | | updatedAt | Timestamp | Fecha y hora de la última actualización | No | Ejemplo de respuesta [ { "id": 103, "campaignId": 5502, "campaignTitle": "Natal 2025 - Promoção Especial", "audience": "lista_fidelidade_natal", "contactId": 9003, "contactName": "Carla Souza", "contactEmail": "[email protected]", "contactPhoneNumber": "+55 31 99999-99999", "ticketId": 78414, "displayTicketId": "2027", "messageSent": false, "sentAt": null, "messageReceived": false, "receivedAt": null, "messageRead": false, "readAt": null, "messageReplied": false, "repliedAt": null, "error": "Número de telefone inválido ou não registrado no WhatsApp", "createdAt": "2025-12-10T09:00:00.000Z", "updatedAt": "2025-12-10T09:00:00.000Z" } ] 5. SINGLE_CONTACT_DELIVERY_EVENTS Devuelve eventos de entrega de mensajes proactivos de envío único (no campañas). Campos devueltos: | Campo | Tipo | Descripción | Dato Posiblemente Sensible | | --- | --- | --- | --- | | id | Entero | ID único del evento de entrega | No | | contactId | Entero | ID del contacto destinatario | No | | contactName | Texto | Nombre del contacto destinatario | Sí | | contactEmail | Texto | Correo electrónico del contacto destinatario | Sí | | contactPhoneNumber | Texto | Teléfono del contacto destinatario | Sí | | ticketId | Entero | ID del ticket generado por el envío, si lo hay | No | | displayTicketId | Texto | ID mostrado al usuario en Cloud Chat — visible en la URL y en la búsqueda por filtros | No | | messageSent | Booleano | Flag que indica si el mensaje fue enviado a la API de WhatsApp (Meta) | No | | sentAt | Timestamp | Fecha y hora del envío | No | | messageReceived | Booleano | Flag que indica si el mensaje fue entregado al dispositivo del contacto | No | | receivedAt | Timestamp | Fecha y hora de la entrega | No | | messageRead | Booleano | Flag que indica si el mensaje fue leído (depende de la configuración de privacidad del contacto) | No | | readAt | Timestamp | Fecha y hora de la lectura | No | | messageReplied | Booleano | Flag que indica si el mensaje fue respondido | No | | repliedAt | Timestamp | Fecha y hora de la primera respuesta | No | | error | Texto | Error de entrega: número inválido, sin WhatsApp, bloqueo, etc. | No | | createdAt | Timestamp | Fecha y hora de creación del registro | No | | updatedAt | Timestamp | Fecha y hora de la última actualización | No | Ejemplo de respuesta [ { "id": 321, "contactId": 555777, "contactName": "Maria Silva", "contactEmail": "[email protected]", "contactPhoneNumber": "+55 11 98888-7777", "ticketId": 78414, "displayTicketId": "2027", "messageSent": true, "sentAt": "2025-08-01T12:00:05.000Z", "messageReceived": true, "receivedAt": "2025-08-01T12:00:08.000Z", "messageRead": true, "readAt": "2025-08-01T12:01:30.000Z", "messageReplied": false, "repliedAt": null, "error": null, "createdAt": "2025-08-01T11:59:59.000Z", "updatedAt": "2025-08-01T12:01:30.000Z" } ] Paso a paso práctico 1. Genera tu API Key en un perfil administrador o supervisor ("Configurações do perfil" (Configuración del perfil) → consulta "Cómo obtener tu API Key"). 2. Elige dónde ejecutarla: es una llamada HTTP GET — usa un cliente de API (Postman, Insomnia) o la terminal con curl. No hace falta programar. 3. Arma la URL reemplazando los campos entre {}: https://{TU_DOMINIO}/api/v2/accounts/{ACCOUNT_ID}/data_extracts?startDate=2025-03-27T00:00:00&endDate=2025-03-27T23:59:59&type=TICKET_METRICS_WITH_AGENT_INFORMATION 4. Agrega el encabezado de autenticación (obligatorio — sin él devuelve 401): api_access_token: {TU_API_KEY} 5. Envía la solicitud (botón Send en Postman, o ejecuta el curl). 6. Lee el resultado: llega un JSON con la lista de tickets; cada campo está descrito en las tablas de tipos de este artículo. Observaciones - Para consultas en tiempo real (no histórico): Cómo consultar contactos, tickets y mensajes en tiempo real vía API - Para modificar datos de tickets vía API: Cómo actualizar y actuar en tickets vía API - Visión general de todas las APIs disponibles: Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API

Última actualización el Sep 22, 2026

Cómo crear tickets vía API en Cloud Chat

📌 ¿Qué permite esta funcionalidad? Esta API permite que usted cree un ticket en Cloud Chat desde cualquier sistema externo, como: - Un sistema de telefonía (ej: cuando llega una llamada) - Un formulario completado en su sitio web - Una integración con CRM, ERP o cualquier herramienta personalizada Al usar esta ruta, usted puede: - Crear un nuevo ticket con estado abierto, pendiente o cerrado - Asociar el ticket a un contacto mediante correo electrónico, teléfono o identificador - Incluir un mensaje inicial (entrada o salida) - Definir atributos personalizados de la conversación en el momento de la creación 🧭 ¿Cuándo usar esta API? Utilice cuando sea necesario iniciar una conversación en Cloud Chat sin que el cliente haya enviado un mensaje por un canal activo. Ejemplos: - ¿Recibió una llamada fuera de Cloud Chat? → Genere un ticket con el resumen de la llamada. - ¿Alguien completó un formulario? → Cree el ticket automáticamente y comience la gestión por correo electrónico. - ¿Quiere centralizar comunicaciones que provienen de otras fuentes? → Use esta API como punto de entrada. 🔗 Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations 🔐 Encabezados obligatorios { "content-type": "application/json", "api_access_token": "SU_TOKEN_DE_API" } 🧾 Cuerpo de la solicitud { "inbox_id": "1", "contact_identifier": "id_123", "contact_email": "[email protected]", "contact_phone_number": "+12345", "message": { "content": "Hola, acabo de completar el formulario en el sitio y necesito ayuda.", "message_type": "incoming" }, "status": "open", // Opcional "private": false, // Opcional "custom_attributes": { // Opcional "example1": "valorXPTO" }, "additional_attributes": { // Opcional "mail_subject": "Protocolo de atención ABCD" }, "assignee_id": "1" // Opcional } 🧠 Explicación de los campos principales inbox_id: Identificador de la Bandeja de entrada que puede obtenerse de la barra del navegador (URI/ruta) al acceder a la configuración de la bandeja. assignee_id (opcional): Identificador del agente que será asignado en el momento de la creación. Para referenciar el contacto, envíe uno de los siguientes tres campos: - contact_identifier: Identificador único del contacto - contact_email: Correo electrónico del contacto - contact_phone_number: Número del contacto message: El mensaje que contiene sus campos: - content: que es el contenido del mensaje - message_type: - "incoming": mensaje recibido del cliente - "outgoing": enviado por el agente - "activity": nota interna - private: si el mensaje es visible para el cliente (false) o interno (true) additional_attributes → mail_subject (opcional) Si el ticket se gestiona vía canal de email, puede usar este campo para personalizar el asunto en el email enviado al contacto cuando comience la conversación. custom_attributes (opcional, pero potente) Puede añadir cualquier campo personalizado de la conversación, ya existente en su configuración, directamente aquí. Para saber cómo crear atributos personalizados, vea esta FAQ. 🎯 ¿El ticket nace como “abierto”? Sí. El ticket se creará con estado “open” por defecto, a menos que se indique el campo estado en la solicitud, lo que lo hace visible y listo para atención inmediata en la bandeja de entrada (inbox) especificada. 🧪 ¿Cómo probar? 1. Acceda a su api_access_token en el panel de configuraciones 2. Copie el ACCOUNT_ID, INBOX_ID y CLOUDCHAT_DOMAIN según lo descrito en esta FAQ de importación 3. Envíe la solicitud vía Postman o script 4. Verifique en Cloud Chat si el ticket apareció en la Bandeja correcta, con la información completa ⚠️ Errores comunes Uso incorrecto de identificadores únicos Los campos identifier, phone_number y email son atributos únicos del contacto. No deben fijarse en solicitudes de creación de tickets. Como la solicitud usa upsert, si se fijan, el resultado será siempre un único contacto siendo actualizado en cada llamada, con todas las conversaciones vinculadas a él. La creación de Ticket no crea contacto La creación manual de tickets vía API no genera nuevos contactos. El sistema solo utiliza contactos ya existentes. Por lo tanto, si el contacto no existe, es necesario crearlo previamente antes de iniciar una conversación. Crea siguiendo esta FAQ!

Última actualización el Sep 22, 2026

Actualización de Atributos Personalizados en Conversaciones vía API

Para actualizar atributos personalizados en conversaciones a través de la API en Cloud Chat, simplemente envía una solicitud PUT a: https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID/custom_attributes Asegúrate de enviar la clave de acceso (API_TOKEN) en los encabezados y los campos solicitados según se describe a continuación. - API_TOKEN: Token de acceso obtenido en la configuración del perfil. - (https://cloudchat.cloudhumans.com/app/accounts/ACCOUNT_ID/profile/settings) Ejemplo de solicitud con campos: curl --request PUT \ --url https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID/custom_attributes \ --header 'api_access_token: API_TOKEN' \ --header 'content-type: application/json' \ --data '{ "custom_attributes": { "to_be_updated": "nuevo_valor", "to_be_removed": null } }' ** Cuerpo de la solicitud** La solicitud debe contener un único campo, custom_attributes, que debe ser un objeto que contenga los atributos personalizados a ser actualizados. Nota: El conversation_id de la conversación a actualizar no debe enviarse en el cuerpo de la solicitud, ya que se pasa como un parámetro en la URL. Ejemplo de solicitud: PUT /conversations/123/custom_attributes { "custom_attributes": { "to_be_updated": "nuevo_valor", "to_be_removed": null } } ** Tipos de atributos** Los atributos personalizados de las conversaciones tienen un tipo definido de valor, establecidos en su configuración, que deben respetarse al usar el endpoint para actualizar los valores: - Texto: Debe recibir valores de tipo String obligatoriamente. - Número: Debe contener solo números. No puede contener caracteres alfabéticos o especiales. - Enlace: Debe ser una URL válida (http o https). El enlace debe terminar obligatoriamente con un dominio válido (ejemplo: .com, .net, .org). - Fecha: Debe estar en el formato ISO8601 (YYYY-MM-DDTHH:MM:SS.sssZ). Ejemplo válido: "2025-01-01T12:00:00.000Z". - Lista: Debe recibir un valor de tipo String, y este valor debe estar presente en la lista de opciones definidas en la configuración del atributo. - Checkbox: Debe ser valores "true" / "false" (cadena), o valores true / false (Booleano). Nota: Para eliminar un valor asignado a un atributo personalizado, simplemente envía null o una cadena vacía (""). El sistema procesará la solicitud y eliminará el atributo del objeto de custom_attributes, garantizando que ya no esté presente en la conversación. ** Manejo de Errores** Si algún valor enviado en el campo custom_attributes no cumple con las reglas definidas, la solicitud no será procesada y devolverá un error específico. - Si la conversación no es encontrada, el sistema devuelve un error "Conversation not found" con código 404. - Si el cuerpo de la solicitud es incorrecto, se devolverá un error "Invalid attributes" con código 422. - Si un atributo no existe en la configuración, se devolverá un error indicando que el atributo no fue encontrado. - Si un valor no respeta el tipo esperado, se mostrará un mensaje informando del problema, como: "number_attr must contain only numeric digits" o "date_attr must be in ISO8601 format (YYYY-MM-DDTHH:MM:SS.sssZ)".

Última actualización el Oct 21, 2025

Cómo eliminar tags de contactos en masa vía API

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. En caso de divergencia entre este artículo y la referencia, prevalece lo que está allí. ::: Cuándo usar - Necesitas eliminar tags de múltiples contactos a la vez sin tener que abrir cada contacto manualmente - Estás ejecutando una rutina de limpieza o corrección de tags en tu base de contactos - Quieres mantener la base organizada después de una campaña o migración Requisitos previos - API Key (API_TOKEN) a mano — consulta Cómo encontrar tu API Key en Cloud Chat - El ACCOUNT_ID de la cuenta - Cada contacto debe tener al menos un identificador entre identifier, email o phone_number Endpoint DELETE https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/contacts/delete_tags Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Tu token de API | Cuerpo de la solicitud El body debe contener un único campo, contacts, que es un array de objetos. Cada objeto representa un contacto y debe contener: | Campo | Obligatorio | Descripción | | --- | --- | --- | | identifier | Al menos 1 de los 3* | Identificador único del contacto | | email | Al menos 1 de los 3* | Correo electrónico del contacto | | phone_number | Al menos 1 de los 3* | Teléfono del contacto | | tags | Sí | Array con los tags a eliminar (por nombre) | *Se debe informar al menos un identificador para localizar el contacto. Ejemplo de solicitud curl --request DELETE \ --url 'https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/contacts/delete_tags' \ --header 'api_access_token: API_TOKEN' \ --header 'content-type: application/json' \ --data '{ "contacts": [ { "identifier": 123, "tags": ["tag-de-massa-1","tag-de-massa-2"] }, { "email": "[email protected]", "tags": ["tag-de-massa-2","tag-de-massa-3"] }, { "phone_number": 5551000000000, "tags": ["tag-de-massa-1","tag-de-massa-3"] } ] }' Cómo se localiza el contacto El sistema busca el contacto en este orden: 1. identifier (primero) 2. email (segundo) 3. phone_number (tercero) :::info A diferencia del endpoint de importación de contactos (que prioriza email), aquí identifier tiene prioridad. ::: Sobre phone_number :::info Si se envía sin el prefijo +, el sistema lo agrega automáticamente (ej.: 5511999998888 → +5511999998888). ::: Observaciones - Para eliminar el contacto (no solo quitar tags): Cómo crear, actualizar y eliminar contactos vía API - Para crear o actualizar contactos (incluida la gestión de tags con tags_add y tags_remove granulares): Cómo importar contactos en masa vía API - Para actualizar atributos personalizados (no tags) en conversaciones: Cómo actualizar atributos personalizados en conversaciones vía API - Visión general de todas las APIs disponibles: Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API

Última actualización el Oct 02, 2026

API - Enviar Mensaje Proactiva por WhatsApp

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. Si este artículo y la referencia no coinciden, vale lo que dice la referencia. ::: Este artículo es la referencia rápida del endpoint de WhatsApp. La guía completa, con Web Widget y etiquetas, está en Disparar mensaje proactivo por API (WhatsApp y Web Widget). Descripción Este endpoint permite crear una conversación proactiva por WhatsApp utilizando una plantilla previamente configurada. Los parámetros de la plantilla son dinámicos y pueden variar según la configuración de la plantilla utilizada. Endpoint URL: POST https://cloudchat.cloudhumans.com/api/v1/accounts/{account_id}/conversations/create_proactive_whatsapp_conversation Headers: - content-type: application/json - api_access_token: Clave de acceso de la API. Parámetros Parámetro en la Ruta account_id - Tipo: String - Obligatorio: Sí - Descripción: ID de la cuenta en el sistema. Parámetros en el Cuerpo 1. inbox_id - Tipo: String - Obligatorio: Sí - Descripción: ID de la bandeja de entrada a la que se enviará el mensaje. 2. phone_number - Tipo: String - Obligatorio: Sí - Descripción: Número de teléfono del destinatario, incluyendo el código del país. 3. template_name - Tipo: String - Obligatorio: Sí - Descripción: Nombre de la plantilla configurada en el sistema. 4. Parámetros Dinámicos de la Plantilla - Tipo: Variados - Obligatorio: Sí, si la plantilla tiene variables (todas son obligatorias) - Descripción: Un campo para cada variable de la plantilla, con su nombre exacto (ver abajo). 5. labels - Tipo: Array de strings - Obligatorio: No - Descripción: Títulos de las etiquetas a aplicar en la conversación creada. Detalles en la guía completa. Sobre los Parámetros Dinámicos Cada variable de la plantilla se convierte en un campo en la raíz del JSON, junto a inbox_id, phone_number y template_name, con el nombre exacto de la variable: - Plantilla con variables con nombre, como Hola {{cliente}}, tu factura de {{monto}} vence mañana: envíe los campos "cliente" y "monto". - Plantilla con variables numeradas, como Hola {{1}}, tu factura de {{2}} vence mañana: envíe los campos "1" y "2". Si falta alguna variable, la API rechaza la solicitud con el error missing params. Los campos que no corresponden a ninguna variable se ignoran. Los nombres de variable con punto o tilde (como {{contact.name}} o {{horário}}) no son aceptados por Meta como variable. Ejemplo de Solicitud curl --location 'https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/create_proactive_whatsapp_conversation' \ --header 'content-type: application/json' \ --header 'api_access_token: ACCESS_TOKEN' \ --data '{ "inbox_id": "INBOX_ID", "phone_number": "+5215512345678", "template_name": "recordatorio_pago", "cliente": "Juan", "monto": "$120.00" }' Notas 1. account_id: El account_id se puede encontrar en el panel administrativo de la cuenta. 2. inbox_id: El inbox_id corresponde al ID de la bandeja de entrada configurada para recibir mensajes. 3. api_access_token: Genera el token en el panel de configuración de API. 4. Parámetros Dinámicos de la Plantilla: Consulte la configuración de su plantilla en el panel administrativo para identificar las variables disponibles y obligatorias. Estos parámetros deben enviarse directamente en la raíz del payload. Importante: Asegúrese de que el número de teléfono esté en formato internacional (E.164), incluyendo el código del país. Límite de solicitudes Este endpoint acepta hasta 200 solicitudes por minuto por clave de API. Por encima de eso, la respuesta es 429 con el encabezado Retry-After (segundos hasta que se libere). Espere ese tiempo antes de reenviar y, en lotes grandes, distribuya los envíos a lo largo de los minutos. Una solicitud que recibió 429 no fue procesada, así que reenviarla no duplica el mensaje. El cuerpo de la respuesta y los demás encabezados están en la sección de límite de Cómo enviar un mensaje proactivo por WhatsApp vía API. Campañas vía API Para enviar a una lista de contactos, use la creación de campañas de la API pública (api.cloudhumans.com), disponible también en el MCP de Cloud Humans: - La audiencia se define por etiqueta: la campaña va a los contactos que tienen la etiqueta. - Antes de crearla, la API pide confirmar cuántos contactos la van a recibir. - El envío sale por el programador de campañas, en pocos minutos o en el horario programado. - La autenticación es por inicio de sesión de usuario (token Bearer), no por el api_access_token de este endpoint. Referencia: Crear una campaña. El endpoint de esta página sigue siendo el camino para el envío uno a uno; para enviar en volumen a través de él, respete el límite de 200 solicitudes por minuto.

Última actualización el Sep 23, 2026

Guía Maestro — Cómo acceder y operar datos de CloudChat mediante API

Esta guía existe para responder una sola pregunta: 👉 “¿Qué API de CloudChat debo usar para lo que quiero hacer?” Antes de copiar cualquier endpoint o escribir código, lee esta página. Evita confusiones, uso incorrecto de APIs y impactos no deseados en producción. 🧠 Visión general: existen 3 tipos de APIs en CloudChat Las APIs de CloudChat no son todas iguales. Se dividen en tres categorías, cada una con un objetivo claro. 📦 APIs de Extracción de Datos Sirven para análisis histórico y reportes. - Exportación en lote (batch) - Uso típico: BI, auditorías, paneles - No modifican datos - Ideales para trabajos programados 🔍 APIs de Consulta en Tiempo Real Sirven para leer datos actuales del sistema. - Buscar contactos - Listar tickets - Leer mensajes - No modifican datos - Usadas en integraciones y automatizaciones en tiempo real ✏️ APIs de Actualización y Acción ⚠️ Estas APIs modifican datos reales en producción. - Resolver tickets - Cambiar estado, prioridad o equipo - Crear mensajes en tickets - Pueden impactar operación, SLA y métricas - Algunas rutas son experimentales o requieren flag activa 📦 Cuando usar APIs de Extracción de Datos Usa APIs de extracción cuando quieras: - Crear reportes - Alimentar herramientas de BI - Realizar auditorías - Analizar largos períodos de tiempo - Exportar muchos tickets a la vez Estas APIs: - Funcionan en lote - Tienen límite de intervalo por solicitud - No deben usarse para lógica de aplicación en tiempo real 👉 Documentación específica: 📦 API de Extracción de Datos (Data Extract API) 🔍 Cuando usar APIs de Consulta en Tiempo Real Usa APIs de consulta cuando necesites responder preguntas ahora, como: - “¿Este contacto ya existe?” - “¿Qué tickets tiene este cliente?” - “¿Cuál es el estado actual de este ticket?” - “¿Qué mensajes se intercambiaron en esta conversación?” Estas APIs: - Son solo lectura (GET) - Operan directamente en la base de producción - No sustituyen la API de extracción 👉 Documentación específica: 🔍 APIs de Consulta en Tiempo Real (Contactos, Tickets y Mensajes) ✏️ Cuando usar APIs de Actualización y Acción ⚠️ Atención: estas APIs modifican datos reales en CloudChat. Usa APIs de acción cuando quieras: - Resolver un ticket vía integración - Actualizar prioridad o equipo responsable - Crear mensajes automáticamente - Sincronizar acciones de otro sistema con CloudChat Estas APIs: - Ejecutan acciones en producción - Pueden afectar operación y métricas - Deben usarse con cuidado y validación 👉 Documentación específica: ✏️ APIs de Actualización y Acción en Tickets 🧩 Regla práctica para escoger la API correcta Pregunta siempre: - ¿Quiero analizar datos históricos? → Usa API de Extracción de Datos - ¿Solo quiero leer datos actuales? → Usa APIs de Consulta en Tiempo Real - ¿Quiero cambiar algo en el sistema? → Usa APIs de Actualización y Acción Si todavía tienes dudas, no continues. Usar la API incorrecta puede generar efectos secundarios inesperados. 🚦 Niveles de cuidado (importante) - Extracción de datos → riesgo bajo - Consulta en tiempo real → riesgo medio - Actualización / acción → riesgo alto Mientras más te acerques a acciones de escritura, más atención y pruebas necesitas. ❌ Errores comunes que esta guía ayuda a evitar - Usar API de extracción para algo que necesita ser en tiempo real - Usar API de escritura pensando que solo es consulta - Mezclar lógica de aplicación con exportación de datos - Modificar tickets sin entender el impacto operacional 📌 Próximos pasos Ahora escoge la documentación correcta para tu caso: - 📦 API de Extracción de Datos (Data Extract API) - 🔍 APIs de Consulta en Tiempo Real (Contactos, Tickets y Mensajes) - ✏️ APIs de Actualización y Acción en Tickets Este guía siempre debe leerse antes de las FAQ técnicas arriba.

Última actualización el Sep 22, 2026

Cómo consultar contactos, tickets y mensajes en tiempo real vía API

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. En caso de discrepancia entre este artículo y la referencia, prevalece lo que está allí. ::: Cuándo usar - Quieres leer datos actuales de Cloud Chat sin modificar nada (consultar un contacto, ver los tickets de un cliente, leer los mensajes de una conversación) - Estás integrando Cloud Chat con otro sistema (CRM, portal interno) que necesita mostrar datos en vivo - Quieres evitar la duplicación de contactos antes de crear un ticket Requisitos previos - API Key de administrador — ver Cómo encontrar tu API Key en Cloud Chat - CLOUDCHAT_DOMAIN y ACCOUNT_ID :::info Si aún no sabes qué tipo de API usar, comienza por la Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API. Esta página cubre solo lectura en tiempo real. ::: Sobre este artículo Las APIs de Consulta en Tiempo Real permiten leer datos actuales de Cloud Chat, directamente desde la base de producción, sin modificar nada. Son ideales para integraciones, automatizaciones y pantallas internas que necesitan responder preguntas como: - "¿Este contacto ya existe?" - "¿Qué tickets tiene este cliente?" - "¿Cuál es el estado actual de este ticket?" - "¿Qué mensajes se intercambiaron en esta conversación?" Sobre el namespace /api/client/ :::info Los endpoints de esta página usan /api/client/accounts/... en lugar del /api/v1/accounts/... usado en otras APIs. Ambos usan el mismo api_access_token para la autenticación. El namespace /api/client/ ofrece endpoints simplificados de lectura — son más directos para consultas puntuales. Para operaciones de escritura (crear, actualizar, eliminar), usa el namespace /api/v1/. ::: Para qué sirven estas APIs Úsalas cuando necesites: - Leer datos ahora - Integrar datos de Cloud Chat con otro sistema - Mostrar información en una aplicación - Tomar decisiones basadas en el estado actual de la atención Para qué no sirven :::warning No uses estas APIs para: - Generar reportes → usa la Data Extract API - Exportar grandes volúmenes de datos → usa la Data Extract API - Analizar períodos largos de tiempo → usa la Data Extract API - Crear o actualizar tickets → usa las APIs de Actualización y Acción en Tickets - Insertar mensajes → usa las APIs de Actualización y Acción en Tickets ::: Autenticación Todos los endpoints exigen: - {CLOUDCHAT_DOMAIN} — dominio de tu cuenta (ej.: cloudchat.cloudhumans.com) - {ACCOUNT_ID} — ID de la cuenta - api_access_token — para los endpoints /api/client/ (secciones 1, 2 y 3), el token debe ser de administrador — los tokens de supervisor o agente reciben 403 Forbidden. La búsqueda por texto libre (sección 1b, namespace /api/v1/) acepta tokens de cualquier perfil de agente 1. Buscar contacto por correo electrónico o teléfono Cuándo usar - Antes de crear un ticket (para saber si el contacto ya existe) - Para asociar datos externos a un contacto - Para evitar duplicación Endpoint GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/contacts?email=EMAIL&phone_number=PHONE Reglas - Al menos uno de los parámetros (email o phone_number) es obligatorio - Si se envían ambos, la API intenta el match más preciso posible Qué devuelve - ID del contacto, nombre, correo electrónico, teléfono - Campos personalizados - Fechas de creación y última actividad 1b. Buscar contactos por texto libre (Search) Cuándo usar Para buscar un contacto por cualquier campo de texto (nombre, correo electrónico, teléfono, identificador, empresa) sin saber exactamente cuál contiene la información. A diferencia del endpoint anterior, este realiza una búsqueda ILIKE (sin distinción de mayúsculas, parcial) en múltiples campos simultáneamente. Endpoint GET /api/v1/accounts/{account_id}/contacts/search?q={termo} Parámetros | Parámetro | Tipo | Obligatorio | Descripción | | --- | --- | --- | --- | | q | string | Sí | Término de búsqueda. Mínimo de 2 caracteres cuando contiene solo letras (busca únicamente name); mínimo de 3 caracteres cuando contiene algún dígito (busca en todos). Por debajo de estos límites, devuelve HTTP 422 | | page | integer | No | Página de resultados (por defecto: 1, 15 resultados por página) | Campos consultados - name — nombre del contacto (siempre se busca) - email — correo electrónico (a partir de 3 caracteres con dígito) - identifier — identificador externo (a partir de 3 caracteres con dígito) - phone_number — teléfono, con y sin el prefijo + (a partir de 3 caracteres con dígito) - company_name — nombre de la empresa (a partir de 3 caracteres con dígito) Respuesta - payload[] — array de contactos encontrados - meta — contiene solo la página actual :::info meta.count y meta.total_pages fueron eliminados para reducir el costo de base de datos en consultas repetidas. Para obtener el total absoluto, usa el endpoint dedicado GET /api/v1/accounts/{account_id}/contacts/search/count?q={termo} (con caché de 30s). ::: Ejemplo GET /api/v1/accounts/1/contacts/search?q=maria&page=1 Devuelve todos los contactos cuyo nombre, correo electrónico, teléfono, identifier o empresa contengan maria. Límite de uso (rate limit) :::warning 40 solicitudes por minuto por token de acceso. Si se excede el límite, la API responde HTTP 429 (Too Many Requests). El mismo límite aplica a /contacts/search/count. ::: Diferencia entre los dos endpoints de búsqueda | | Búsqueda por correo/teléfono | Búsqueda por texto libre | | --- | --- | --- | | Namespace | /api/client/ | /api/v1/ | | Campos | Solo correo o teléfono | name, email, identifier, phone, company | | Tipo de match | Exacto | Parcial (ILIKE) | | Paginación | No | Sí (15 por página) | | Total de resultados | — | Endpoint separado (/search/count) | 2. Listar los tickets de un contacto Cuándo usar Ya tienes el CONTACT_ID y quieres listar los tickets de ese cliente: - Mostrar el historial de atenciones - Ver tickets abiertos o resueltos - Integrar con un CRM o portal interno Endpoint GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}/conversations?page=1&limit=10 Parámetros - page — obligatorio - limit — opcional (por defecto: 10) Qué devuelve - IDs de los tickets - Estado (open, resolved, etc.) - Prioridad - Inbox - Fechas de creación - Si fue iniciado por una campaña 3. Listar los mensajes de un ticket Cuándo usar Para recuperar el historial de mensajes de un ticket: - Auditoría en tiempo real - Mostrar la conversación en otra interfaz - Depurar integraciones Endpoint GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/messages?page=1&limit=10 Qué devuelve - Contenido del mensaje - Tipo (incoming / outgoing) - Pública o privada - Fecha de creación - Estado del mensaje - Enlaces de los adjuntos (si existen) Cómo se conectan estas APIs (flujo típico) 1. Buscar el contacto por correo electrónico o teléfono 2. Obtener el CONTACT_ID 3. Listar los tickets de ese contacto 4. Elegir un ticket 5. Listar los mensajes del ticket :::success Todo esto sin modificar ningún dato. ::: Nivel de riesgo Riesgo medio — no modifican datos, pero consultan la base de producción en tiempo real. :::info Buenas prácticas: - Evita bucles agresivos - Usa caché cuando sea posible - No las uses para exportación masiva ::: Errores comunes :::warning - Usar estas APIs para reportes históricos - Olvidar el parámetro page - Confundir CONTACT_ID con CONVERSATION_ID - Intentar crear o actualizar datos con GET ::: Etiquetas (labels) de la conversación y cómo encontrar el contact_id Las etiquetas aplicadas a la conversación tienen su propio endpoint (en Chatwoot, la base de Cloud Chat, se llaman labels): GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/labels Para encontrar el contact_id a partir del CONVERSATION_ID no se necesita un endpoint separado — el propio detalle de la conversación ya lo devuelve: GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID} En la respuesta, meta.sender.id es el contact_id del contacto dueño de la conversación. El mismo objeto meta.sender incluye nombre, correo electrónico, teléfono y otros identificadores. Ambos endpoints exigen un api_access_token de un usuario con el permiso adecuado. Observaciones - Para cambiar estado, prioridad o equipo: Cómo actualizar y actuar en tickets vía API - Para reportes y BI (extracción histórica): Cómo extraer datos en lote vía API - Visión general de las APIs disponibles: Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API

Última actualización el Oct 02, 2026

Cómo actualizar y actuar en tickets vía API

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. En caso de divergencia entre este artículo y la referencia, prevalece lo que está allí. ::: Cuándo usar - Quieres cambiar el estado (resolver, reabrir), la prioridad o el equipo de un ticket mediante una integración - Necesitas enviar mensajes automáticamente en un ticket existente - Necesitas gestionar labels (etiquetas) en tickets Requisitos previos - API Key de administrador o supervisor — ver Cómo encontrar tu API Key en Cloud Chat - CLOUDCHAT_DOMAIN, ACCOUNT_ID, CONVERSATION_ID (ID interno) y/o DISPLAY_ID (ID visible en la UI) :::error Estas APIs escriben en producción. Los cambios impactan SLAs, métricas y la operación. Valida el estado actual del ticket antes de hacer cambios y prueba en un entorno controlado antes de usarlas en producción. ::: Sobre este artículo Estas APIs permiten modificar datos reales de tickets — cambiar estado, prioridad, equipo y enviar mensajes. Para solo consultar datos (sin modificar), usa Cómo consultar contactos, tickets y mensajes en tiempo real vía API. Autenticación Todos los endpoints exigen: | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Token de administrador o supervisor | 1. Cambiar el estado del ticket (resolver, reabrir, etc.) Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/toggle_status Body { "status": "resolved" } Valores aceptados | Valor | Descripción | | --- | --- | | open | Reabrir ticket | | resolved | Resolver ticket | | pending | Marcar como pendiente | Ejemplo curl -X POST \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/toggle_status' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{"status": "resolved"}' Devuelve el objeto de la conversación actualizada con estado 200 OK. :::warning El endpoint PUT /api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID} no cambia el estado — solo acepta el campo priority. Para cambiar el estado, usa siempre el toggle_status de arriba. ::: 2. Cambiar la prioridad del ticket Endpoint PUT https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}} Body { "priority": "high" } Valores aceptados | Valor | Descripción | | --- | --- | | nil / null | Sin prioridad | | low | Baja | | medium | Media | | high | Alta | | urgent | Urgente | Ejemplo curl -X PUT \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{"priority": "high"}' :::warning Este endpoint (PUT .../conversations/{ID}) acepta solamente el campo priority. Campos como status, team_id u otros se ignoran silenciosamente. ::: 3. Cambiar estado, prioridad y equipo (Client API) Para cambiar estado, prioridad y/o equipo en una sola llamada, usa la Client API: Endpoint PATCH https://{{CLOUDCHAT_DOMAIN}}/api/client/accounts/{{ACCOUNT_ID}}/conversations/{{DISPLAY_ID}} :::warning Este endpoint usa el display_id (ID visible en Cloud Chat), no el conversation_id interno. ::: :::warning Esta Client API exige token de administrador. Los tokens de supervisor o agente reciben 403 Forbidden. Si usas token de supervisor, cambia el status con el toggle_status (sección 1) y la priority con el PUT (sección 2). ::: Body { "status": "resolved", "priority": "high", "team_id": "1" } Campos aceptados | Campo | Descripción | | --- | --- | | status | Estado del ticket (open, resolved, pending) | | priority | Prioridad (low, medium, high, urgent) | | team_id | ID del equipo para la reasignación | Todos los campos son opcionales — envía solo lo que quieras cambiar. Si el team_id informado no existe en la cuenta, la API devuelve 422 con {"error": "Team not found"}. Ejemplo curl -X PATCH \ 'https://{{CLOUDCHAT_DOMAIN}}/api/client/accounts/{{ACCOUNT_ID}}/conversations/{{DISPLAY_ID}}' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{"status": "resolved"}' 4. Crear un mensaje en un ticket Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/messages Body { "content": "Olá! Segue atualização sobre sua solicitação.", "message_type": "outgoing" } Campos | Campo | Obligatorio | Descripción | | --- | --- | --- | | content | Sí | Contenido del mensaje | | message_type | Sí | incoming (mensaje del cliente) u outgoing (mensaje del agente/sistema) | | private | No | true para nota interna (no visible para el cliente) | Ejemplo curl -X POST \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/messages' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{ "content": "Sua solicitação foi processada.", "message_type": "outgoing" }' 5. Gestionar labels (etiquetas) de un ticket :::warning El endpoint PUT /conversations/{ID} no acepta el campo labels. Si envías labels en el body del PUT, la API devuelve 200 pero ignora silenciosamente el campo. Para gestionar labels, usa el endpoint dedicado de abajo. ::: Endpoint POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/labels Body { "labels": ["suporte", "prioridade-alta"], "append": true } Campos | Campo | Tipo | Obligatorio | Descripción | | --- | --- | --- | --- | | labels | array de strings | Sí | Lista de labels a aplicar | | append | boolean | No | true agrega a las labels existentes. false u omitido reemplaza todas | Ejemplo curl -X POST \ 'https://cloudchat.cloudhumans.com/api/v1/accounts/1/conversations/12345/labels' \ -H 'api_access_token: SEU_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"labels": ["suporte", "urgente"], "append": true}' Campos que no se pueden cambiar vía PUT/PATCH Algunos campos parecen editables pero la API los ignora silenciosamente (devuelve 200 sin error): | Campo | Situación | Qué hacer | | --- | --- | --- | | mail_subject | Atributo dentro de additional_attributes. Solo puede definirse al crear el ticket. Los intentos de actualización vía PUT se ignoran | No hay workaround vía API. Si el asunto del correo debe ser diferente, crea un nuevo ticket | | labels | Ignorado en el PUT/PATCH del ticket | Usa el endpoint dedicado POST .../conversations/{ID}/labels (sección 5) | Resumen: qué endpoint usar para cada acción | Acción deseada | Endpoint | Método | | --- | --- | --- | | Cambiar estado (resolver, reabrir) | .../conversations/{ID}/toggle_status | POST | | Cambiar prioridad | .../conversations/{ID} | PUT | | Cambiar estado + prioridad + equipo | /api/client/.../conversations/{DISPLAY_ID} | PATCH | | Crear mensaje en el ticket | .../conversations/{ID}/messages | POST | | Gestionar labels | .../conversations/{ID}/labels | POST | Flujo seguro recomendado 1. Consulta el estado actual del ticket antes de modificarlo — ver Cómo consultar contactos, tickets y mensajes en tiempo real vía API 2. Valida si la acción es necesaria (ej.: no resolver un ticket que ya está resuelto) 3. Ejecuta el cambio usando el endpoint correcto de la tabla de arriba 4. Confirma el resultado verificando la respuesta de la API Dónde encontrar los parámetros - CLOUDCHAT_DOMAIN — dominio visible en la URL del navegador - ACCOUNT_ID — en Configuración de la cuenta - CONVERSATION_ID — ID interno de la conversación (devuelto por las APIs de consulta) - DISPLAY_ID — ID visible en la interfaz de Cloud Chat (usado solo en la Client API) - API_TOKEN — en https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings Observaciones - Para crear tickets nuevos vía API: Cómo crear tickets vía API en Cloud Chat - Para actualizar atributos personalizados en conversaciones: Cómo actualizar atributos personalizados en conversaciones vía API - Para consultar sin modificar datos: Cómo consultar contactos, tickets y mensajes en tiempo real vía API - Visión general de las APIs disponibles: Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API

Última actualización el Oct 02, 2026

Crear o actualizar un artículo en la Centro de Ayuda

Para crear un nuevo artículo en la centro de ayuda de Cloud Chat, simplemente realiza una solicitud POST a: http://{CLOUDCHAT_DOMAIN}/v1/accounts/{ACCOUNT_ID}/portals/{PORTAL_SLUG}/articles Solicitud con campos de ejemplo: curl --location 'http://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/portals/{PORTAL_SLUG}/articles' \ --header 'Content-Type: application/json' \ --header 'api_access_token: BSvG6cFEqsMxKi72F6mvcjWc' \ --data '{ "content": "Contenido del artículo...", "status": 0, //Debe comenzar como borrador! "title": "Título del artículo", "author_id": 1, "category_id": 1 }' Para marcar el artículo como "publicado" es necesario realizar una segunda solicitud, esta vez un PUT, cambiando el estado a 1: curl --location --request PUT 'http://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/portals/{PORTAL_SLUG}/articles/{ARTICLE_ID}' \ --header 'Content-Type: application/json' \ --header 'api_access_token: BSvG6cFEqsMxKi72F6mvcjWc' \ --data '{ "status": 1, // --- Los demás campos son opcionales --- //"title": "...", //"content": "...", //"author_id": 2, //"category_id": 20, }' Parámetros necesarios CLOUDCHAT_DOMAIN: Puedes obtener tu dominio iniciando sesión en tu cuenta en CloudChat. Es la parte que aparece en la URL del navegador: ACCOUNT_ID: Obtenido en la sección de configuraciones de la cuenta: API_TOKEN: Obtenido en la configuración de tu perfil de usuario en Cloud Chat (https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings) author_id y category_id se pueden encontrar inspeccionando la solicitud que se realiza en el navegador durante algún cambio en la propia pantalla de artículos:

Última actualización el Dec 18, 2025

Cómo crear artículos en el Centro de Ayuda vía API

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. En caso de diferencia entre este artículo y la referencia, prevalece lo que está allí. ::: Cuándo usarlo - Quieres crear un nuevo artículo en el Centro de Ayuda de Cloud Chat vía API - Estás automatizando la publicación de contenido a partir de otra fuente - Necesitas una referencia rápida del endpoint de creación Requisitos previos - API Key a mano — consulta Cómo encontrar tu API Key en Cloud Chat - ACCOUNT_ID y PORTAL_SLUG (slug del portal, ej.: cloud-chat) - author_id y category_id registrados Endpoint POST /api/v1/accounts/{id}/portals/{slug}/articles Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Tu token de API | Campos obligatorios | Campo | Descripción | | --- | --- | | title | Título del artículo | | content | Contenido en Markdown | | status | 0 (borrador) o 1 (publicado) — recomendamos crearlo como 0 y publicarlo después con PUT | | author_id | ID del autor | | category_id | ID de la categoría | Ejemplo curl --location 'https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/portals/{PORTAL_SLUG}/articles' \ --header 'Content-Type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{ "title": "Título do artigo", "content": "Conteúdo em Markdown...", "status": 0, "author_id": 1, "category_id": 1 }' :::info Después de crearlo como borrador (status=0), publícalo haciendo un PUT con status=1 en el mismo article_id. Consulta el flujo completo en Cómo crear, actualizar o eliminar artículos en el Centro de Ayuda vía API. ::: Observaciones - Para el flujo completo (crear + publicar + actualizar + eliminar): Cómo crear, actualizar o eliminar artículos en el Centro de Ayuda vía API - Visión general de todas las APIs disponibles: Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API

Última actualización el Oct 02, 2026

Disparar mensaje proactivo por API (WhatsApp y Widget Web)

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. En caso de discrepancia entre este artículo y la referencia, prevalece lo que está allí. ::: Cuándo usar - Cuando un sistema externo (tu backend, CRM, automatización de marketing) necesita iniciar una conversación con un contacto específico — sin que un agente la abra manualmente. - Para avisos transaccionales y proactivos por contacto: confirmación de pedido, recordatorio de pago, actualización de estado, reanudación del carrito. - En dos canales, con la misma autenticación (api_access_token): - WhatsApp — envía un mensaje de plantilla aprobado al teléfono del contacto. - Widget Web de área autenticada (HMAC) — muestra un mensaje que aparece cuando el contacto vuelve a estar autenticado en el chat de tu sitio/app. Requisitos previos - Un Token de Acceso API de Cloud Chat (disponible en tu perfil, en Perfil → Configuraciones → Access Token). Debe estar en el encabezado api_access_token. - El account_id de tu cuenta (aparece en la URL de Cloud Chat). - La dirección de tu instancia de Cloud Chat, que es el dominio que aparece en el navegador cuando accedes a la plataforma (ej.: cloudchat5.cloudhumans.com). Las llamadas deben dirigirse a esa dirección. Una dirección de otra instancia responde con 401. - El token vale sólo para la instancia en la que fue generado. Si generas uno nuevo, el anterior deja de funcionar inmediatamente, así que actualiza en todos los sistemas que lo usan. - Para WhatsApp: una bandeja de entrada de WhatsApp conectada + una plantilla aprobada por Meta. - Para Widget Web: una bandeja de entrada de Widget Web con HMAC obligatorio (área autenticada / identidad verificada) + un contacto identificable. Cómo funciona Autenticación Los dos endpoints usan el mismo encabezado. Nunca expongas el token en el front-end — estos disparos son servidor a servidor. api_access_token: TU_API_ACCESS_TOKEN Content-Type: application/json :::warning Envía el token sólo en el encabezado api_access_token, solo el valor, sin comillas ni prefijo Bearer. No agregues un encabezado Authorization, porque la llamada será rechazada con 401. ::: WhatsApp: disparo por plantilla Envía (push) un mensaje activo — llega al WhatsApp del contacto en el momento. Como es WhatsApp, el contenido tiene que ser una plantilla aprobada. POST https://{TU_DOMINIO}/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_whatsapp_conversation {TU_DOMINIO} es la dirección de tu instancia (ej.: cloudchat5.cloudhumans.com). { "inbox_id": 123, "phone_number": "+5511999998888", "template_name": "lembrete_pago", "labels": ["campaña-x", "vip"], "cliente": "Juan", "valor": "R$ 120,00" } - inbox_id — la bandeja de WhatsApp desde la cual se envía el mensaje. - phone_number — teléfono del contacto en formato internacional E.164 (con + y código del país, ej.: +5511999998888). - template_name — nombre de la plantilla aprobada. - Variables de la plantilla — cada variable debe enviarse como un campo al nivel raíz del cuerpo (hermano de inbox_id/phone_number/template_name), con el nombre de la variable de la plantilla. Ej.: una plantilla con las variables cliente y valor debe recibir los campos "cliente" y "valor". Si la plantilla usa variables numeradas ({{1}}, {{2}}), los campos son "1" y "2". No pongas estos campos dentro de un objeto template_params. - labels (opcional) — arreglo de cadenas con títulos de etiquetas a aplicar en la conversación creada (ej.: ["campaña-x", "vip"]). Los títulos se normalizan en minúsculas y las etiquetas se agregan sin eliminar las existentes. Las etiquetas nuevas se crean automáticamente en la cuenta solo si el token tiene permisos de administrador o CX Engineer; con token de agente, los títulos inexistentes son ignorados. Detalles en Cómo enviar mensaje proactivo por WhatsApp vía API. WhatsApp: límite de solicitudes El endpoint de WhatsApp acepta hasta 200 solicitudes por minuto por clave de API. Por encima de eso, la respuesta es 429 con el encabezado Retry-After (segundos hasta liberar). Espera ese tiempo antes de reintentar y, en lotes grandes, distribuye los envíos a lo largo de los minutos. Una solicitud que recibe 429 no fue procesada, así que reenviarla no duplica el mensaje. El cuerpo de la respuesta, otros encabezados y cómo se cuenta el límite están en Cuáles son los límites de solicitud (rate limits) de las rutas de la API de Cloud Chat?. Widget Web (área autenticada): disparo por contacto Muestra un mensaje que aparece de forma pasiva: el widget no envía push — el mensaje aparece en la próxima vez que el contacto abra el chat autenticado en el área logada. Puedes disparar incluso a quienes todavía no abrieron el chat (identificando mediante identifier). POST https://{TU_DOMINIO}/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_web_widget_conversation { "inbox_id": 456, "identifier": "usuario-42", "content": "¡Hola Juan! Vi que tu plan vence mañana. ¿Puedo ayudarte a renovarlo?", "idempotency_key": "renovacion-usuario-42-2026-06-28" } - inbox_id — la bandeja del Web Widget (HMAC obligatorio). - Identificación del contacto — envía exactamente uno de estos: - identifier — tu identificador estable del usuario. Crea el contacto si aún no existe. - email — usa un contacto ya identificable con ese email. - contact_id — el ID del contacto en Cloud Chat. - content — el texto libre del mensaje (no necesita plantilla). - idempotency_key (opcional) — consulta abajo. - contact_attributes (opcional) — atributos/nombre para enriquecer el contacto en la creación. :::info La entrega es pasiva: el mensaje solo es visible después de que el contacto autentique la sesión en el widget (HMAC). Por eso, esta disparo es exclusivo de bandejas de área logada. ::: Widget Web: formato del identificador El identifier necesita ser exactamente igual al valor que tu app usa para generar el HMAC en el SDK del widget para ese usuario. Si difieren (ej.: tú disparas "42", pero el widget envía "usuario-42"), Cloud Chat tratará como contactos diferentes y el mensaje no aparecerá para el usuario. - identifier — cadena estable (el mismo del HMAC). Se recomienda usar el ID del usuario en tu sistema. - email — un email válido de un contacto ya identificable. Widget Web: múltiples bandejas y contactos sin teléfono - Múltiples bandejas de Web Widget. El identifier identifica al contacto en toda la cuenta, por lo que el mismo usuario puede ser alcanzado en diferentes bandejas (ej.: productos o áreas logadas distintas) usando el mismo identifier. El disparo siempre ocurre por bandeja (inbox_id): cada bandeja mantiene su propia conversación/sesión con el contacto. Para hablar con el usuario en dos áreas, envía un mensaje a cada inbox_id. - Cuando no hay número de teléfono. A diferencia de WhatsApp (donde el número es la identidad), en el Web Widget el contacto se identifica por identifier/email y no necesita tener teléfono. Los contactos sin número son completamente soportados — el teléfono no es relevante en este canal. Idempotencia (Web Widget) Reenvíos son seguros si utilizas idempotency_key. La misma clave, dentro de 24 horas, devuelve la misma conversación, en lugar de crear una copia duplicada — útil para intentos de reenvío. Reutilizar la misma clave para un contacto diferente es rechazado (error idempotency_key_contact_mismatch). Principales errores | Código | Significado | | --- | --- | | inbox_id_required / inbox_not_found | Bandeja de entrada ausente o no encontrada en la cuenta. | | contact_not_identifiable | email/contact_id proporcionado no corresponde a un contacto identificable. | | ambiguous_contact_match | Los datos corresponden a más de un contacto — refine la identificación. | | invalid_contact_attributes | contact_attributes inválidos para crear el contacto. | | idempotency_key_contact_mismatch | La idempotency_key ya fue usada para otro contacto. | Observaciones - WhatsApp = activo (push, vía plantilla); Widget Web = pasivo (texto libre, en la próxima sesión autenticada). Elige el canal según el tipo de entrega deseada. - El disparo es por contacto en ambos canales (uno a uno), no una campaña masiva. - La conversación creada queda fuera de la cola/SLA de los agentes hasta que el contacto participe — no cuenta como atención activa mientras nadie responda. - Mantén el api_access_token sólo en el servidor.

Última actualización el Oct 21, 2026

Cómo extraer respuestas de botones (Quick Reply) de campañas de WhatsApp vía API

Cuándo usarlo - Cuando envías una campaña de WhatsApp con una plantilla que tiene botones de respuesta rápida (Quick Reply) y quieres saber, por campaña, quién tocó cuál botón y cuándo. - Para armar métricas de campaña y de botones (tasa de respuesta, cuál opción fue la más elegida) desde tu backend, sin necesidad de abrir conversación por conversación en la interfaz. - Es un endpoint servidor a servidor, solo de lectura. No hay interfaz para esto en Cloud Chat — los datos salen por la API. Requisitos previos - Un Token de Acceso API de administrador o supervisor de Cloud Chat. Para obtener el tuyo: haz clic en tu avatar (esquina inferior izquierda) → Configuraciones de Perfil y baja hasta la sección "Token de acceso" — el campo viene enmascarado; usa los botones al lado para revelarlo o copiarlo. Con un token de agente el endpoint devuelve 401/403. Los usuarios con acceso solo a ClaudIA no ven esa sección. Sección "Token de acceso" en las Configuraciones de Perfil - El account_id de tu cuenta — es el número justo después de /accounts/ en la URL de Cloud Chat. Ejemplo: en https://cloudchat.cloudhumans.com/app/accounts/1/dashboard, el account_id es 1. - Una campaña de WhatsApp ya enviada, cuya plantilla tenga botones de Quick Reply. - El display_id de la campaña — mira la sección de abajo, "Cómo encontrar el ID de la campaña". Cómo encontrar el ID de la campaña (display_id) La interfaz de Cloud Chat no muestra el ID de la campaña (no aparece en el listado ni en la URL). Para encontrarlo, usa el endpoint de listado de campañas con el mismo token: curl -s 'https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/campaigns?query=TITULO_DE_LA_CAMPANA&campaign_type=one_off' \ -H 'api_access_token: TU_API_ACCESS_TOKEN' - query busca por el título de la campaña (el mismo que aparece en el listado de la interfaz) y campaign_type=one_off restringe a las campañas únicas — juntos, normalmente devuelven directo la campaña deseada. - Para listar todas las campañas (extracción masiva), llámalo sin query, paginando: curl -s 'https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/campaigns?page=1&per_page=100' \ -H 'api_access_token: TU_API_ACCESS_TOKEN' - La respuesta viene paginada en el formato { "data": [...], "meta": {...} } — default 20 por página, per_page máximo 100; itera page de 1 hasta meta.total_pages. - El campo id de cada campaña devuelta ya es el display_id que usas en el endpoint de respuestas — no lo confundas con ningún id interno. { "id": 22081, "title": "Mi campaña", "campaign_status": "completed", "campaign_type": "one_off" } Cómo funciona Autenticación api_access_token: TU_API_ACCESS_TOKEN Ruta GET https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/campaigns/{DISPLAY_ID}/responses - {ACCOUNT_ID} — id de la cuenta. - {DISPLAY_ID} — display_id de la campaña. Parámetros de query (opcionales) - page — página (default 1). - per_page — ítems por página (default 100, máximo 500). Ejemplo de llamada curl -s 'https://cloudchat.cloudhumans.com/api/v1/accounts/7/campaigns/156/responses?page=1&per_page=100' \ -H 'api_access_token: TU_API_ACCESS_TOKEN' Tip: este curl se puede importar directo en Postman (File → Import → Raw text) — solo cambia el token y los ids. Respuesta La respuesta tiene tres partes: responses, summary y meta. { "responses": [ { "id": 27749371, "content": "Sim, tenho interesse e desejo prosseguir", "inbox_id": 174, "conversation_id": 1777, "message_type": 0, "status": "delivered", "additional_attributes": { "campaign_id": 188, "template_button_reply": true, "template_button_payload": "Sim, tenho interesse e desejo prosseguir" }, "created_at": 1784781019, "sender": { "id": 1350835, "type": "contact", "name": "João da Silva", "phone_number": "+5511999998888" } } ], "summary": { "Sim, tenho interesse e desejo prosseguir": 1 }, "meta": { "current_page": 1, "total_count": 1, "total_pages": 1 } } - responses — cada ítem es el mensaje de respuesta del contacto (el toque en el botón). Campos útiles: - content — el texto del botón tocado. - sender — el contacto que respondió (nombre + teléfono). - additional_attributes.template_button_payload — el payload del botón (repite el texto del botón). - conversation_id / created_at — dónde y cuándo ocurrió la respuesta (created_at es un timestamp Unix, en segundos). - summary — conteo agregado por texto del botón: { "<texto del botón>": <cantidad> }. Es el atajo para la métrica "cuántas personas eligieron cada opción". El summary siempre considera la campaña entera, sin importar la página. - meta — paginación: current_page, total_count (total de respuestas de la campaña), total_pages. Atención: total_pages depende del per_page usado. Para exportar todas las respuestas, usa per_page=500 e itera page de 1 hasta total_pages. Errores comunes - 401 Unauthorized — token inválido, expirado/regenerado, o el header api_access_token no fue enviado. - 401/403 — el token es de un usuario agente (el endpoint exige administrador o supervisor en la cuenta). - 404 Not Found — campaña no encontrada: o el número usado no es el display_id (mira "Cómo encontrar el ID de la campaña"), o la campaña pertenece a otra cuenta distinta del {ACCOUNT_ID} de la URL. - responses vacío con la campaña correcta — la plantilla no tenía botones Quick Reply, nadie tocó un botón todavía, o la campaña fue enviada antes del lanzamiento del recurso (sin datos retroactivos). Notas importantes - Sin historial retroactivo. Solo aparecen respuestas registradas a partir del lanzamiento del recurso. Las campañas antiguas no se completan retroactivamente. - El identificador de análisis es el texto del botón. Como las plantillas no definen un payload propio, el payload solo repite el texto del botón. Agrupa/analiza por el texto (es lo que hace el summary). - Los conteos son por toque, no por contacto único. Si el mismo contacto toca más de un botón (o el mismo botón más de una vez), cada toque se vuelve una respuesta y entra en el summary. Para métricas por contacto único, deduplica por sender.id de tu lado. - Solo cuentan los toques de botón Quick Reply de campaña. Si el contacto responde con texto libre (en vez de tocar un botón), esa respuesta no entra aquí — el vínculo con la campaña solo existe cuando es un toque de botón de un envío de campaña.

Última actualización el Aug 18, 2026

Cómo encontrar tu API Key en Cloud Chat

Cuándo usarlo - Estás configurando una integración y necesitas el api_access_token para autenticar las solicitudes - Quieres reutilizar la misma clave en otro flujo (HubSpot, Postman, un script) - Necesitas rotar la clave por seguridad Requisitos previos - Haber iniciado sesión en Cloud Chat con tu propia cuenta — la clave se genera por usuario, no por cuenta Sobre este artículo La clave de API estaba al final de la pantalla de Configuración del Perfil, junto a la foto, la firma y las notificaciones. Ahora tiene una página propia, MCP / API, en el mismo menú de tu avatar. Allí están los dos temas de integración de tu usuario: el Servidor MCP, para conectar Cloud Humans a asistentes de IA, y la Clave de API, para autenticar llamadas a la API de Cloud Chat. :::info Si abres el menú y todavía no ves MCP / API, pero encuentras Token de acceso al final de la Configuración del Perfil, tu instancia aún no recibió esta actualización. El valor de la clave es exactamente el mismo en los dos lugares — cópialo de donde esté. ::: Paso a paso Paso 1 — Abrir la página MCP / API 1. En la esquina inferior izquierda, haz clic en tu avatar para abrir el menú 2. Haz clic en MCP / API Paso 2 — Copiar la clave 1. Ve a la sección Clave de API, la segunda de la página 2. La clave aparece enmascarada. Haz clic en el icono de ojo para revelarla, o usa directamente el botón de copiar para llevar el valor al portapapeles :::success Usa este valor en el header api_access_token de tus solicitudes a la API de Cloud Chat. ::: Paso 3 — Generar una clave nueva (opcional) Hazlo solo cuando necesites rotar la clave — por ejemplo, si sospechas que se filtró. 1. En la sección Clave de API, haz clic en el botón de flechas circulares, a la izquierda del botón de copiar 2. Confirma en la ventana que se abre :::warning La clave anterior queda invalidada de inmediato. Cualquier integración que siga usando el valor anterior deja de funcionar hasta que se actualice con la clave nueva. ::: Observaciones :::warning La clave de API es personal y por usuario: da acceso a los datos de tu cuenta, con tus permisos. Trátala como una contraseña — no la compartas públicamente ni la subas a repositorios. ::: - ¿No encuentras la sección Clave de API? En cuentas que solo usan el panel de ClaudIA, esta sección no aparece — solo la del Servidor MCP. Habla con tu equipo de atención de Cloud Humans. - El Servidor MCP es otra cosa. Está en la misma página, pero no usa ninguna clave: la autorización ocurre al iniciar sesión con tu propia cuenta de Cloud Humans. El paso a paso está en la guía de conexión del MCP. - Para usar la clave en una extracción de datos por lotes: Cómo extraer datos por lotes vía API (Data Extract API)

Última actualización el Sep 17, 2026

Integración Jira en CloudChat

¿Qué es la integración con Jira? La integración con Jira permite que los agentes creen, vinculen y desvinculen issues de Jira directamente desde una conversación en CloudChat. Esto elimina la necesidad de cambiar entre herramientas y garantiza la trazabilidad entre atención y tickets de producto/ingeniería. Requisitos previos - Cuenta en Jira Cloud (Atlassian) - Un usuario en Jira con permiso para crear issues en los proyectos deseados - Un token API de Jira (generado en https://id.atlassian.net/manage-profile/security/api-tokens) ¿Cómo configurar la integración? 1. Accede a Configuración > Integraciones en el menú lateral de CloudChat. 2. Haz clic en Jira y luego en Conectar. 3. Completa los campos: - URL del sitio Jira — por ejemplo: https://tuempresa.atlassian.net - Correo electrónico — el correo del usuario de Jira que se usará para las llamadas a la API - Token API — el token generado en el paso anterior 4. Haz clic en Guardar. La integración estará disponible para todos los agentes de la cuenta. ¿Cómo crear un issue en Jira desde una conversación? 1. Abre una conversación en CloudChat. 2. En el encabezado de la conversación, haz clic en el ícono de Jira. 3. Haz clic en Crear issue. 4. Completa los campos obligatorios (marcados con *): - Título — resumen del issue - Proyecto — el proyecto de Jira donde se creará el issue - Tipo de issue — solo aparece después de seleccionar el proyecto (ej: Bug, Task, Story) 5. Opcionalmente, completa: - Descripción — detalles adicionales - Prioridad — nivel de urgencia - Responsable — a quién se asignará el issue 6. Haz clic en Crear. El issue se creará en Jira con un enlace a la conversación en la descripción. ¿Cómo vincular un issue ya existente? 1. En el panel de Jira dentro de la conversación, haz clic en Vincular issue existente. 2. Busca por el título o la clave del issue (ej: PROJ-123). 3. Haz clic en el issue deseado para vincularlo. Se añadirá un comentario automáticamente en el issue de Jira informando que fue vinculado a la conversación. ¿Cómo desvincular un issue? 1. En el panel de Jira dentro de la conversación, localiza el issue vinculado. 2. Haz clic en el ícono de papelera al lado del issue. Se añadirá un comentario en Jira informando que el vínculo con la conversación fue removido. ¿Un issue puede estar vinculado a más de una conversación? Sí. El mismo issue de Jira puede estar vinculado a múltiples conversaciones en CloudChat. Cada vínculo genera un comentario en Jira con el enlace a la conversación correspondiente. ¿Qué información aparece en la tarjeta del issue? La tarjeta muestra: - Clave del issue (ej: PROJ-123) - Título - Estado actual en Jira (ej: To Do, In Progress, Done) La información se actualiza automáticamente cada vez que abres el panel. ¿En qué idioma se añaden los comentarios en Jira? Los comentarios se añaden en el idioma configurado en la cuenta de CloudChat. ¿Qué versiones de Jira son compatibles? La integración funciona exclusivamente con Jira Cloud. Jira Server y Jira Data Center no son soportados.

Última actualización el Sep 02, 2026

Migración del historial de tickets a Cloud Chat

Al migrar desde otro helpdesk, las conversaciones antiguas no se transfieren automáticamente — quedan en la herramienta anterior. Si quieres conservarlas en Cloud Chat, mira abajo lo que tienes que entregarnos. Lo que necesitas entregarnos 1. Bandeja de entrada lista. Asegúrate de que la migración de tu canal esté concluida y de que la bandeja de entrada esté creada y activa en Cloud Chat — solo importamos el historial después de eso (sin bandeja de entrada, no hay adónde importar). 2. El historial en formato JSON. Exporta tus conversaciones antiguas en un archivo JSON con la clave conversations_data — una lista de tickets. Cada ticket tiene: - Fechas del ticket: created_at (apertura) y updated_at (última actualización), en ISO 8601 (ej.: 2024-01-15T10:30:00Z). - contact: identifier (obligatorio, único y estable por cliente) y, opcionales, name, email, phone_number (E.164). - messages: cada mensaje con content (texto), message_type (incoming = cliente, outgoing = agente, activity = nota interna), created_at (ISO 8601) y private (true para nota interna). - custom_attributes (recomendado): la información que quieres conservar como referencia. Guarda el ID del ticket antiguo en external_helpdesk_id (trazabilidad), e incluye las tags y atributos del ticket que quieras mantener (ej.: priority, source_queue, tags). Esas tags entran como información/etiqueta de referencia en la conversación importada — no como la tag nativa que filtra en la plataforma. Dinos cuáles quieres conservar. Ejemplo: { "conversations_data": [ { "contact": { "identifier": "user_6782902", "name": "John Doe", "email": "[email protected]", "phone_number": "+5511988887777" }, "custom_attributes": { "external_helpdesk_id": "ZD-78901", "priority": "high" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-16T14:22:00Z", "messages": [ { "content": "Meu pedido não chegou.", "message_type": "incoming", "created_at": "2024-01-15T10:30:00Z", "private": false }, { "content": "Oi! Já verifiquei, sai hoje.", "message_type": "outgoing", "created_at": "2024-01-15T10:31:00Z", "private": false }, { "content": "Cliente VIP, priorizar.", "message_type": "activity", "created_at": "2024-01-15T11:16:00Z", "private": true } ] } ] } 3. Acuerda el alcance con tu contacto. Alinea con nosotros el período (todo el historial o un recorte, ej.: los últimos 12 meses), qué tags/atributos quieres conservar, y si quieres separar por canal (WhatsApp, Instagram, correo electrónico…). 4. Envía el archivo. Sube el/los archivo(s) .json a la carpeta de Google Drive que compartimos contigo — o, si prefieres, envía un enlace del archivo (Google Drive, OneDrive, el que sea). Si quieres mantener los canales separados, envía un archivo por canal (ej.: historico_whatsapp.json). 5. Empieza por una muestra. Antes del archivo completo, envía 20–50 tickets en el formato — nosotros los importamos en un ambiente de validación, tú los revisas, y solo entonces procesamos todo. :::info No se importa: imágenes y adjuntos. La migración es de texto (mensajes, notas internas y metadatos). Si un adjunto era esencial, incluye su enlace en el texto del mensaje. Reglas: fechas siempre en ISO 8601 (si no puedes enviarlas en UTC, avísanos la zona horaria); identifier realmente único (dos clientes con el mismo valor se convierten en uno solo); archivo en UTF-8. ::: Cloud Humans hace la importación por ti Con el archivo enviado, el equipo de Cloud Humans ejecuta la importación — importamos por lotes, respetando los límites de la plataforma, y confirmamos el resultado contigo. No necesitas tocar ninguna API ni darnos acceso a tu herramienta antigua. ¿Prefieres hacerlo por tu cuenta? Este es el paso a paso Si tu equipo tiene una persona desarrolladora y prefiere ejecutar la importación, usa la API. Además del archivo en el formato de arriba, vas a necesitar: API Key (ver Cómo obtener tu API Key), CLOUDCHAT_DOMAIN, ACCOUNT_ID e INBOX_ID. Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Tu token de API | El cuerpo es el mismo conversations_data descrito arriba. Límites — cada solicitud acepta como máximo 10.000 tickets o 15 MB. Para volúmenes mayores, divide en varias solicitudes. El identifier del contacto es único (dedup). Para que los custom_attributes aparezcan formateados en el panel, defínelos antes en Settings → Custom Attributes (alcance: Conversation). Dónde encontrar los IDs CLOUDCHAT_DOMAIN Parte de la URL al iniciar sesión en tu cuenta: ACCOUNT_ID En "Configurações da conta" (Configuración de la cuenta): API_TOKEN En https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings: INBOX_ID ID de la bandeja que recibirá los tickets. Se puede obtener en la URL de la pestaña de configuración de la bandeja de entrada: Observaciones - Para crear tickets nuevos vía API (no importación histórica): Cómo crear tickets vía API en Cloud Chat - Para importar contactos antes o junto con la importación de tickets: Cómo importar contactos de forma masiva vía API - Visión general de las APIs disponibles: Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API

Última actualización el Sep 22, 2026

Crear y seguir campañas mediante la API pública

Cuándo usar - Quieres lanzar campañas desde tu propio sistema, sin abrir la pantalla de Cloud Chat. - Quieres estimar cuántos contactos alcanza una audiencia antes de gastar en envíos. - Necesitas seguir el estado de una campaña de forma programática. Requisitos previos :::error Crear una campaña dispara el envío. No existe un borrador intermedio en la API, igual que en la pantalla. No uses el endpoint de creación para "montar y revisar después". ::: - Clave de API de la cuenta. - Perfil con permiso para campañas. El perfil de agente no puede disparar, ni en la API ni en la pantalla. Cómo funciona Verificar el alcance antes de enviar Existe un endpoint que resuelve la audiencia y devuelve cuántos contactos realmente alcanza. Úsalo antes de crear: es lo que evita descubrir el tamaño real del envío después de que ya salió. La confirmación obligatoria de destinatarios En la creación, necesitas declarar cuántos destinatarios esperas alcanzar. El sistema compara ese número con lo que la audiencia realmente resuelve: - Si coincide, la campaña se crea y entra en la cola de envío. - Si difiere, la respuesta es un error de conflicto y nada se crea. :::info Esta es la protección contra envíos no intencionados. Existe precisamente porque no hay borrador: si tu audiencia creció desde la última vez que la consultaste, la solicitud falla en lugar de enviar a más personas de las que esperabas. ::: Canales disponibles La creación cubre los tres canales que también cubre la pantalla: WhatsApp, correo electrónico y widget web. Descubrir plantillas y variables Como quien llama por la API no ve la pantalla, existen dos endpoints de descubrimiento: uno lista las plantillas disponibles en la cuenta y el otro, las variables que puedes usar. Úsalos para montar el cuerpo de la campaña sin depender de que alguien revise en el panel. Consultar el estado después Hay un endpoint de lectura para seguir la campaña creada. Observaciones - La referencia completa de los endpoints está en la documentación pública de la API. Las mismas capacidades también están disponibles como herramienta de MCP. - La campaña creada por la API nace en el mismo estado que la creada por la pantalla, y es el mismo programador quien envía. La API es la puerta de entrada, no un camino de envío diferente. - Existen límites de destinatarios, por audiencia bruta y por canal. Si la solicitud supera el límite, recibes un error de validación y no se crea nada.

Última actualización el Sep 22, 2026

Qué significa el aviso "Falha no envio do webhook" (Falla en el envío del webhook) en los mensajes

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. En caso de discrepancia entre este artículo y la referencia, prevalece lo que está allí. ::: Cuándo usar - Viste el aviso "Falha no envio do webhook" (Falla en el envío del webhook) en los mensajes de un ticket y quieres saber qué significa - Quieres saber si este aviso afecta la atención o el envío de mensajes Qué es este aviso El aviso aparece cuando una regla de automatización de tu cuenta intenta enviar datos a un endpoint externo (webhook) y ese endpoint no confirma la recepción. Es común en cuentas que usan automatizaciones del tipo "Mensagem recebida" (Mensaje recibido) o "Ticket resolvido" (Ticket resuelto) para enviar una copia de los datos a un sistema propio (hoja de cálculo, script, ERP, herramienta de BI). :::info El aviso no afecta la atención. El envío y la recepción de mensajes (incluso en WhatsApp) siguen funcionando normalmente, y la ClaudIA tampoco se ve afectada. Lo único que falla es la integración paralela que debería recibir esos datos. ::: Cómo investigar 1. Ve a Configurações → Automação (Configuración → Automatización) e identifica las reglas que envían datos a un endpoint externo. 2. Verifica la URL de destino de cada una. 3. Prueba esa URL fuera de Cloud Chat: necesita responder confirmando la recepción. Si redirige (respuesta 302) o empieza a exigir inicio de sesión, el envío se considera fallido. Caso común — Google Apps Script: la implementación debe estar configurada como "Cualquier persona tiene acceso", ejecutándose como el propietario del script. Cuando se modifica la implementación (o el enlace antiguo empieza a exigir inicio de sesión), el endpoint comienza a redirigir y todos los intentos fallan — a veces durante meses, sin que nadie lo note. Observaciones - Quien administra el endpoint (tu equipo o quien se encarga del script/integración) es quien necesita corregir la implementación — el ajuste no se hace en Cloud Chat. - Si la integración ya no se usa, el camino más limpio es desactivar la regla de automatización que hace el envío, y el aviso deja de aparecer.

Última actualización el Oct 02, 2026

Payload del Webhook de CloudChat

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. En caso de divergencia entre este artículo y la referencia, prevalece lo que está allí. ::: Payload enviado por el Webhook de CloudChat Cuando una automatización dispara un webhook, realiza un POST HTTP a la URL configurada, enviando un JSON con la siguiente información principal: Estructura del payload (JSON) CampoDescripcióneventEl tipo de evento que disparó el webhook (ej.: message_created, conversation_created, etc.)contentEl contenido del mensajemessage_typeTipo de mensaje (incoming, outgoing, etc.)conversationObjeto con datos de la conversación, incluyendo id, status, etc.senderObjeto con datos del remitente (contacto), incluyendo id, name, email, phone_number, etc.accountObjeto con datos de la cuenta, incluyendo idinboxObjeto con datos de la inbox/canalcontactDatos del contacto asociado Ejemplo práctico (basado en el código) Como se ve en el ejemplo de integración con Rasa: chatwoot / implementation-examples / rasa-agent-bot-demo / rasa_flask_router.py @app.route('/rasa', methods=['POST']) def rasa(): data = request.get_json() message_type = data['message_type'] message = data['content'] conversation = data['conversation']['id'] Eventos compatibles con webhooks Según lo definido en el modelo: chatwoot / chatwoot / app / models / webhook.rb ALLOWED_WEBHOOK_EVENTS = %w[conversation_status_changed conversation_updated conversation_created contact_created contact_updated message_created message_updated webwidget_triggered inbox_created inbox_updated conversation_typing_on conversation_typing_off].freeze Resumen del JSON típico que llega a tu endpoint: webhook_payload_example.json { "event": "message_created", "message_type": "incoming", "content": "Olá, preciso de ajuda!", "id": 12345, "conversation": { En resumen: El webhook envía un POST con JSON que contiene los datos del evento, de la conversación, del contacto/remitente, de la cuenta y de la inbox, junto con el contenido del mensaje y el tipo de mensaje. Esto permite que el sistema externo (el que recibe el webhook) sepa exactamente qué ocurrió y tome la acción adecuada.

Última actualización el Oct 02, 2026

¿Cuáles son los límites de solicitudes (rate limits) de las rutas de la API de Cloud Chat?

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. Si hay diferencias entre este artículo y la referencia, prevalece lo que está allí. ::: Cuándo usar - Integras sistemas externos con la API de Cloud Chat y necesitas planificar el volumen de llamadas sin ser bloqueado. - Recibiste un error 429 (Too Many Requests) y quieres entender el motivo. - Estás importando contactos de forma masiva, enviando conversaciones proactivas de WhatsApp, generando informes o extracciones de datos vía API y necesitas saber el ritmo seguro de llamadas. Sobre este artículo Algunas rutas de la API de Cloud Chat tienen un límite de solicitudes por minuto (rate limit). Este límite existe para proteger la estabilidad de la plataforma en operaciones más pesadas, como la importación masiva de contactos, la generación de informes y el envío de mensajes proactivos. La mayoría de las rutas de la API no tiene un límite específico configurado: los límites a continuación se aplican solo a las rutas listadas en la tabla. Si todavía no tienes tu clave de API a mano, consulta Cómo encontrar tu API Key en Cloud Chat. Límites por ruta La siguiente tabla muestra el límite de solicitudes por minuto de cada ruta: | Ruta | Límite / minuto | | --- | --- | | contacts/external_import | 500 | | conversations/create_proactive_whatsapp_conversation | 200 | | contacts/bulk_create | 100 | | contacts/search y contacts/search/count | 40 | | v2/reports | 20 | | v2/data_extracts | 20 | | integrations/hooks/{id}/process_event (eventos del Copilot) | 20 | | conversations/{id}/transcript | 10 | | messages/{id}/transcription | 10 | :::info El límite de integrations/hooks/{id}/process_event se aplica solo a los eventos del Copilot (reformular, corregir ortografía, resumir tono, expandir, entre otros). Los eventos heredados de sugerencia de respuesta, resumen o etiqueta no están sujetos a este límite. ::: Cómo se aplica el límite - Ventana fija de 1 minuto. El contador se reinicia cada minuto calendario; no es una ventana deslizante. - Clave de conteo. En la mayoría de las rutas, el límite se cuenta por clave de API (api_access_token). En las rutas que también pueden llamarse desde el panel de Cloud Chat (create_proactive_whatsapp_conversation, process_event, contacts/search/contacts/search/count y messages/{id}/transcription), el límite se cuenta tanto por la clave de API como por la sesión iniciada en el panel; es decir, cada agente o token tiene su propio contador. - No es por IP. El límite no depende de la dirección IP de origen, solo de la clave de API (o de la sesión) usada en la llamada. Qué pasa al superar el límite Al superar el límite de una ruta, la API responde con el status 429 y el cuerpo: { "error": "Rate limit exceeded. Retry later.", "retry_after": 42 } La respuesta también incluye estos headers: | Header | Descripción | | --- | --- | | X-RateLimit-Limit | Límite configurado para esta ruta. | | X-RateLimit-Remaining | Siempre 0 en una respuesta 429. | | X-RateLimit-Reset | Timestamp (epoch) de cuándo se reinicia la ventana. | | Retry-After | Segundos hasta que puedas intentarlo de nuevo. | :::warning Respeta siempre el Retry-After antes de volver a intentarlo. Hacer un nuevo intento inmediato en una ruta ya limitada solo prolonga el bloqueo y no acelera la entrega. ::: Observaciones - La mayoría de las rutas de la API no tiene un rate limit específico: los límites anteriores cubren solo las rutas listadas en esta tabla. - Si necesitas un límite mayor para alguna de estas rutas en un caso de uso legítimo (por ejemplo, una migración puntual de un gran volumen de contactos), habla con el equipo de soporte de Cloud Humans antes de ejecutar la operación. - Para la importación masiva de contactos, consulta también Cómo importar contactos de forma masiva vía API. - Para una visión general de la autenticación y la operación de datos vía API, consulta la Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API.

Última actualización el Oct 02, 2026

Cómo fusionar (merge) contactos vía API

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. Si hay diferencias entre este artículo y la referencia, prevalece lo que está allí. ::: Cuándo usar - Tienes al mismo cliente duplicado en dos contactos (ej.: entró por canales diferentes) y quieres unirlos en uno solo - Estás deduplicando la base de contactos mediante una integración - Quieres consolidar el historial (conversaciones, mensajes, notas) de dos contactos en un único registro Requisitos previos - Tu API Key a mano — consulta Cómo encontrar tu API Key en Cloud Chat - CLOUDCHAT_DOMAIN y ACCOUNT_ID - Los dos ids de contacto que se fusionarán — para encontrarlos, usa la búsqueda descrita en Cómo consultar contactos, tickets y mensajes en tiempo real vía API Endpoint POST https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/actions/contact_merge Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Tu token de API | Cuerpo de la solicitud { "base_contact_id": 100, "mergee_contact_id": 250 } | Campo | Descripción | | --- | --- | | base_contact_id | Contacto que permanece (ganador de la fusión) | | mergee_contact_id | Contacto que será absorbido y eliminado | Cómo funciona Al fusionar: - Todas las conversaciones, mensajes, notas, bandejas de entrada (contact_inboxes), respuestas de CSAT y eventos de campaña del contacto absorbido pasan al contacto base. - En los campos de perfil (name, email, phone_number, identifier, additional_attributes, custom_attributes), gana el contacto base. Donde el contacto base esté vacío, se aprovecha el valor del contacto absorbido. - El contacto absorbido (mergee_contact_id) se elimina al final. - Respuesta 200 con el contacto base resultante. :::error La fusión es irreversible. Queda registrada una auditoría interna, pero no existe "deshacer". Confirma cuál id es el base_contact_id (el que permanece) antes de hacer la llamada — invertir los dos elimina el contacto equivocado. ::: Ejemplo de solicitud curl -X POST \ 'https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/actions/contact_merge' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{ "base_contact_id": 100, "mergee_contact_id": 250 }' Errores comunes | Status | Significado | | --- | --- | | 404 Not Found | Uno de los contactos (base_contact_id o mergee_contact_id) no existe en la cuenta | | 422 Unprocessable Entity | Payload inválido (falta base_contact_id o mergee_contact_id) | Observaciones - Crear, actualizar y eliminar contactos individualmente: Cómo crear, actualizar y eliminar contactos vía API - Encontrar los ids de los contactos: Cómo consultar contactos, tickets y mensajes en tiempo real vía API - Visión general de todas las APIs disponibles: Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API

Última actualización el Oct 02, 2026

Cómo conectar el MCP Server de Cloud Humans en Claude

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. En caso de diferencias entre este artículo y la referencia, prevalece lo que está allí. ::: Cuándo usarlo - Quieres gestionar el contenido de tu base de conocimiento directamente desde Claude — listar, crear y editar sin salir de la conversación - Quieres dejar de mantener la misma base de conocimiento en varios lugares - Usas otro cliente MCP (Claude Code, Cursor, VS Code) y quieres conectarlo a Cloud Humans :::info El MCP Server de Cloud Humans está en Beta. Las funcionalidades de gestión de contenido ya están disponibles y se están agregando nuevas. Si algo no funciona como esperabas, habla con tu equipo de atención de Cloud Humans. ::: Requisitos previos - Una cuenta de Cloud Humans activa — el inicio de sesión del conector se hace con el mismo correo electrónico y contraseña que ya usas en la plataforma - Un cliente MCP que acepte conectores personalizados (en Claude, esto depende de tu plan) - No es necesario generar, solicitar a Cloud Humans ni pegar en ningún lugar ningún token ni clave de API — la autorización ocurre en la pantalla de inicio de sesión Sobre este artículo El MCP Server de Cloud Humans es la dirección que le da a tu asistente de IA acceso a las herramientas de Cloud Humans. Una vez conectado, conversas normalmente con Claude y este puede consultar y modificar tu contenido en Cloud Humans. La dirección del servidor es: https://mcp.cloudhumans.com/openapi/cloudhumans/mcp :::warning Esta dirección no es una página para abrir en el navegador. Si pegas esta URL en la barra de direcciones, verás el mensaje {"detail":"missing_token"}. Esto es esperado y no es un error: no significa que te falten permisos ni que necesites un token. La dirección solo funciona cuando se agrega como conector dentro de tu cliente de IA, que es lo que explican los pasos a continuación. ::: Este artículo trata sobre conectar tu asistente de IA a Cloud Humans. Si lo que buscas es el camino inverso — conectar los agentes de ClaudIA a servidores MCP externos —, consulta Cómo configurar servidores MCP para los agentes de ClaudIA. Paso a paso Etapa 1 — Abrir la configuración de conectores 1. En Claude, abre la Configuración 2. Ve a la sección Conectores Etapa 2 — Agregar como conector personalizado 1. Haz clic en Agregar conector personalizado :::warning Tiene que ser un conector personalizado (custom connector). Cloud Humans no aparece en la lista de conectores predefinidos — si la buscas allí, no la vas a encontrar. ::: 2. En Nombre, escribe algo que reconozcas después (por ejemplo, Cloud Humans) 3. En URL, pega la dirección del servidor: https://mcp.cloudhumans.com/openapi/cloudhumans/mcp 4. Confirma para agregarlo Etapa 3 — Iniciar sesión y autorizar 1. Haz clic en Conectar en el conector que acabas de crear 2. Se abrirá una pantalla de inicio de sesión de Cloud Humans, que te pedirá correo electrónico y contraseña 3. Inicia sesión con tu cuenta de Cloud Humans — la misma que usas en la plataforma 4. Después de iniciar sesión, el navegador vuelve automáticamente a Claude y el conector pasa a aparecer como conectado :::info Tienes cerca de 10 minutos para completar el inicio de sesión después de hacer clic en Conectar. Si tardas más, la pantalla expira — solo haz clic en Conectar de nuevo y vuelve a empezar. ::: Etapa 4 — Probar Vuelve a una conversación y pide algo simple, como: Lista los contenidos de mi base de conocimiento en Cloud Humans. Si Claude responde con tus contenidos, todo está bien. :::info Si tu usuario tiene acceso a más de una cuenta o proyecto en Cloud Humans, indica en la conversación cuál quieres usar. Sin eso, el asistente no tiene cómo adivinar en cuál actuar y te pedirá que lo especifiques. ::: Observaciones - La conexión es válida por 30 días y se renueva automáticamente mientras la uses. Pasado ese plazo, Claude te pide iniciar sesión de nuevo — solo repite la Etapa 3. - Cambiar la contraseña o perder el acceso a tu cuenta termina la conexión de inmediato. Es el comportamiento esperado: quien pierde el acceso a la plataforma también pierde el acceso a través del conector. - Los permisos son exactamente los de tu cuenta. El conector no amplía ni reduce lo que ya podías ver y editar en Cloud Humans, y cada persona que se conecta usa su propia cuenta. - Funciona con otros clientes MCP. La dirección y el flujo de inicio de sesión son los mismos en cualquier cliente que admita servidores MCP remotos con inicio de sesión — lo único que cambia es dónde está la opción para agregar el conector. - Si la pantalla de inicio de sesión no se abre y sigues viendo {"detail":"missing_token"}, casi siempre la dirección se abrió en el navegador en lugar de agregarse como conector personalizado. Repite la Etapa 2.

Última actualización el Oct 02, 2026

Cómo crear, actualizar y eliminar contactos vía API

:::info La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. En caso de diferencias entre este artículo y la referencia, prevalece lo que está allí. ::: Cuándo usar - Necesitas crear, consultar, actualizar o eliminar un contacto específico en Cloud Chat vía API - Quieres cambiar solo algunos campos de un contacto sin borrar los demás - Estás integrando Cloud Chat con otro sistema que gestiona contactos de forma individual Requisitos previos - API Key a mano — ver Cómo encontrar tu API Key en Cloud Chat - CLOUDCHAT_DOMAIN y ACCOUNT_ID :::info Este artículo cubre operaciones sobre un contacto a la vez mediante el endpoint REST estándar. Para importar o actualizar varios contactos a la vez, usa Cómo importar contactos de forma masiva vía API. Para solo leer datos, consulta Cómo consultar contactos, tickets y mensajes en tiempo real vía API. ::: Permisos por operación | Operación | Permiso mínimo | | --- | --- | | Crear, consultar, actualizar | Cualquier perfil de agente | | Eliminar contacto | Administrador | | Consultar por correo electrónico (/contacts/email) | Administrador | :::warning Si puedes crear y actualizar pero recibes 403 Forbidden al eliminar, tu token es de agente. Usa un token de usuario administrador para eliminar contactos. ::: Crear contacto POST https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts El body es un objeto JSON simple — al menos uno entre email, phone_number o identifier: { "name": "Maria Silva", "email": "[email protected]", "phone_number": "+5511999998888", "identifier": "CRM-123", "additional_attributes": { "company_name": "Acme" }, "custom_attributes": { "plano": "premium" } } - Opcional: envía inbox_id (y source_id) para vincular el contacto a una bandeja de entrada desde el inicio. - Respuesta 200 con el contacto creado, incluyendo el id. Consultar contacto Por id: GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID} Por correo electrónico exacto (requiere administrador): GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/[email protected] :::info Para buscar por texto libre (nombre, teléfono, empresa, parcial), usa el endpoint de búsqueda — ver Cómo consultar contactos, tickets y mensajes en tiempo real vía API, sección "Buscar contatos por texto livre" (Buscar contactos por texto libre). ::: Actualizar contacto PUT https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID} Envía solo los campos que quieres cambiar: { "name": "Maria S. Silva", "custom_attributes": { "plano": "enterprise" } } :::success A diferencia de la importación masiva con upsert: true, la actualización individual no borra los campos que no envíes. ::: - Los custom_attributes se combinan con los ya existentes (no se borran los demás). - Para eliminar un atributo personalizado específico: POST https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}/destroy_custom_attributes { "custom_attributes": ["plano"] } - Respuesta 200 con el contacto actualizado. Eliminar contacto DELETE https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID} - Requiere usuario administrador. - Respuesta 200 en caso de éxito. :::warning Si el contacto está en línea en el momento de la llamada, la eliminación se bloquea y devuelve 422. Inténtalo de nuevo cuando no esté activo. ::: :::info Para eliminar solo las tags de los contactos (sin eliminar el contacto), consulta Cómo eliminar tags de contactos de forma masiva vía API. ::: Ejemplo de solicitud (actualizar) curl -X PUT \ 'https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{ "name": "Maria S. Silva" }' Errores comunes | Status | Significado | | --- | --- | | 403 Forbidden | Token sin permiso (eliminar requiere administrador) | | 422 Unprocessable Entity | Datos inválidos, o intento de eliminar un contacto en línea | | 404 Not Found | Contacto no encontrado en la cuenta | Dónde encontrar los parámetros - CLOUDCHAT_DOMAIN — dominio visible en la URL del navegador - ACCOUNT_ID — en "Configurações da conta" (Configuración de la cuenta) - API_TOKEN — en https://{CLOUDCHAT_DOMAIN}/app/accounts/{ACCOUNT_ID}/profile/settings Observaciones - Importar varios contactos a la vez: Cómo importar contactos de forma masiva vía API - Importar 1 contacto desde un sistema externo (upsert, conserva los campos): Cómo importar un contacto individual vía API - Unir contactos duplicados: Cómo fusionar (merge) contactos vía API - Visión general de todas las APIs disponibles: Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API

Última actualización el Oct 02, 2026