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:

Primero busca por email
Si no se envió email, busca por identifier
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

API: Importación de contacto individual