Contactos y bandejas

Vinculá una persona de tu sistema con un contacto del CRM, identificá la bandeja correcta y obtené una conversación donde trabajar. Los ejemplos usan las variables de la introducción.

Entender los identificadores

Guardá el vínculo entre el ID de tu sistema y contact_id. Un contacto puede tener varias bandejas y conversaciones. No busques al cliente por su nombre como si fuera único.

1. Elegir la bandeja

curl --fail-with-body \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/inboxes" \
  --header "api_access_token: $CRM_API_TOKEN"

Revisá payload[] y elegí el id de la bandeja de prueba. channel_type identifica el tipo de canal; Channel::Api puede representar una conexión externa, no necesariamente WhatsApp. No deduzcas el teléfono o las capacidades solo por ese tipo.

2. Buscar antes de crear

curl --fail-with-body --get \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/contacts/search" \
  --header "api_access_token: $CRM_API_TOKEN" \
  --data-urlencode "q=+5491155551234" \
  --data-urlencode "page=1"

La búsqueda es parcial y puede devolver varios contactos en payload. Compará el teléfono normalizado, email o identifier con tu registro antes de elegir. --data-urlencode conserva el + del teléfono.

Si no existe, crealo. El siguiente ejemplo está pensado para una bandeja de WhatsApp nativo (Channel::Whatsapp), donde el CRM puede derivar source_id del teléfono:

curl --fail-with-body --request POST \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/contacts" \
  --header "api_access_token: $CRM_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Ana Pérez",
    "phone_number": "+5491155551234",
    "identifier": "erp-cliente-991",
    "inbox_id": 12
  }'

Tomá el nuevo ID de payload.contact.id y el identificador del canal de payload.contact_inbox.source_id. identifier sirve para guardar tu referencia externa; no convierte el POST en una operación idempotente. Si la creación devuelve un conflicto de validación, volvé a buscar y verificá qué registro existe.

3. Abrir una conversación

Para WhatsApp nativo, enviá el contacto y la bandeja:

curl --fail-with-body --request POST \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/conversations" \
  --header "api_access_token: $CRM_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "contact_id": 991, "inbox_id": 12, "status": "open" }'

El id de la respuesta es el que usarás en las rutas de mensajes. La creación puede reutilizar y reabrir una conversación existente en bandejas API o configuradas para una única conversación. Un POST exitoso no siempre significa una conversación nueva.

Para contactos existentes podés consultar GET .../contacts/{contact_id}/contactable_inboxes y reutilizar el source_id de la bandeja correcta. Al crear la conversación, pasá también contact_id e inbox_id; no uses un source_id aislado.

En Messenger e Instagram necesitás una identidad válida del canal, obtenida del contacto que escribió. Un número de teléfono no reemplaza ese identificador. Para canales API externos, reutilizá el vínculo existente y respetá el contrato de su conector; no inventes un source_id.

4. Mantener los datos al día

curl --fail-with-body --request PUT \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/contacts/991" \
  --header "api_access_token: $CRM_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Ana Pérez", "custom_attributes": { "numero_cliente": "C-991" } }'

Definí primero numero_cliente como atributo de contacto en el CRM. En contactos, los custom_attributes enviados se combinan con los existentes. En conversaciones el comportamiento es distinto: el objeto se reemplaza.

Comprobar el resultado

Abrí /app/accounts/123/conversations/4821 en tu panel, reemplazando ambos IDs. Verificá contacto, bandeja y estado antes de enviar un mensaje. Crear una conversación no evita las restricciones de envío del canal.