Sincronizar contactos con tu CRM

1. Creá o actualizá el contactoCopiar el enlace a esta sección

Crear o actualizar un contacto busca el contacto por phone: si existe lo actualiza, si no lo crea. Es la opción segura para reintentos: llamarla dos veces con el mismo teléfono no duplica. Acepta phone (obligatorio), name y email, y pide conversations:write.

curl -X POST "https://api.funnelchat.com/api/v1/contacts/update-or-create" \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5491100000000",
    "name": "Ana Pérez",
    "email": "ana@example.com"
  }'

Respuesta de ejemplo (recortada a algunos campos):

{
  "id": 102578466,
  "name": "Ana Pérez",
  "email": "ana@example.com",
  "phone": "5491100000000",
  "whatsapp_id": "",
  "has_phone": true,
  "country_code": "",
  "status": 1,
  "created_at": "2026-10-04T21:23:45.000000Z",
  "active_conversation": 0,
  "unread_messages": 0
}

• Tratá 200 y 201 como éxito. En las pruebas del 04-10 respondió 201 al crear el contacto y 200 cuando ya existía, con el mismo id; la especificación documenta solo 200 (conocido en v0).
• El teléfono, con o sin +. Los dos encuentran el mismo contacto, y la API lo guarda sin + (detalle).
• Guardá el id en tu CRM. Lo piden los pasos siguientes. Para otros datos de la ficha (notas, asesor, favorito), usá Actualizar un contacto con ese id.

2. Encontrá el campo personalizadoCopiar el enlace a esta sección

Los campos personalizados guardan datos propios de tu negocio, como plan, ciudad o fecha de compra. Para cargar un valor necesitás el id del campo: buscalo por nombre con Listar campos personalizados y quedate con el que coincida exacto.

curl -G "https://api.funnelchat.com/api/v1/custom-fields" \
  --data-urlencode "name=plan" \
  --data-urlencode "perPage=100" \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "Accept: application/json"

Respuesta de ejemplo (recortada, sin links ni meta):

{
  "data": [
    {
      "id": 3101,
      "name": "plan",
      "type": 0,
      "description": null,
      "created_at": "2026-09-01T10:00:00.000000Z"
    }
  ]
}

3. Guardá el valor en el contactoCopiar el enlace a esta sección

Asignar un campo personalizado a contactos recibe una lista: cada elemento lleva customFieldId, contactId y value (texto). Podés cargar varios campos y varios contactos en una sola llamada.

curl -X POST "https://api.funnelchat.com/api/v1/contacts/attach-custom-field" \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '[
    { "customFieldId": 3101, "contactId": 102578466, "value": "Premium" }
  ]'

Respuesta de ejemplo (según la especificación, un resultado por elemento):

[
  {
    "message": "Custom field value attached successfully.",
    "status": 201
  }
]

Un elemento con status: 403 trae en message si el campo o el contacto no son de tu cuenta. Para borrar un valor, usá Quitar un campo personalizado de contactos.

4. Leé las etiquetas del contactoCopiar el enlace a esta sección

Para reflejar en tu CRM el segmento de cada contacto, Listar las etiquetas de un contacto devuelve sus etiquetas, paginadas con perPage.

curl -G "https://api.funnelchat.com/api/v1/contacts/102578466/tags" \
  --data-urlencode "perPage=100" \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "Accept: application/json"

Respuesta de ejemplo (recortada, sin links ni meta; … marca valores cuyo formato la especificación no documenta):

{
  "data": [
    {
      "id": 4001,
      "name": "Cliente",
      "description": "",
      "color": "…",
      "assigned_at": "…"
    }
  ]
}

5. Traé todos los contactosCopiar el enlace a esta sección

Para la carga inicial, o para reconciliar, recorré Listar contactos página por página:

• Mandá siempre perPage (hasta 100) y un orden estable, como orderBy=id con orderByMethod=asc.
• Para la página siguiente, seguí links.next: conserva perPage y los filtros de tu consulta.
• Pará cuando links.next sea null (o cuando meta.current_page llegue a meta.last_page).

Para traer solo una parte, sumá filtros como created_from (fecha de alta) o tag_ids[] con tag_mode (all, any o exclude).

curl -G "https://api.funnelchat.com/api/v1/contacts" \
  --data-urlencode "perPage=100" \
  --data-urlencode "page=1" \
  --data-urlencode "orderBy=id" \
  --data-urlencode "orderByMethod=asc" \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "Accept: application/json"

Respuesta de ejemplo (recortada a un contacto y sin links):

{
  "data": [
    {
      "id": 102578466,
      "name": "Ana Pérez",
      "email": "ana@example.com",
      "phone": "5491100000000",
      "has_phone": true,
      "status": 1,
      "created_at": "2026-10-04T21:23:45.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "path": "https://api.funnelchat.com/api/v1/contacts",
    "per_page": 100,
    "to": 100,
    "total": 419
  }
}