Primeros pasos

Lo que es común a toda la API, sin importar el área (accounts, conversations o communities): una sola URL, una sola forma de autenticarte y los mismos errores.

La URL baseCopiar el enlace a esta sección

https://api.funnelchat.com

Es la única dirección pública de la API. La URL de una llamada es la URL base + la ruta completa, que empieza con /api/v1/…: por ejemplo, https://api.funnelchat.com/api/v1/contacts. Cada llamada llega al mismo lugar y se reparte sola al área dueña de la ruta; vos no elegís el área.

• Las referencias siguen siendo una por área, pero todas usan esta URL base.
• Los hosts internos de cada área dejan de publicarse y las claves van a dejar de funcionar contra ellos. Usá siempre https://api.funnelchat.com. Una clave usada contra un host interno, cuando se encienda esa exigencia, recibe 403 use_public_endpoint: pendiente de fecha.
• Las URL que arma la API en sus respuestas, como los enlaces de paginación, también salen con https://api.funnelchat.com.

Autenticarte con tu claveCopiar el enlace a esta sección

Cada llamada lleva la clave completa en la cabecera Authorization, tal como se mostró al crearla, incluido el <id>| del principio:

Authorization: Bearer <id>|fc_live_...

La clave se crea en la pantalla Desarrolladores de tu cuenta. Los permisos, cómo guardarla y qué pasa al revocarla están en Autenticación y permisos; el paso a paso con la primera llamada, en la Guía rápida.

Un ejemplo de listaCopiar el enlace a esta sección

Esta llamada lista tus primeros cinco contactos (área conversations). Con una clave la respuesta siempre viene paginada:

curl "https://api.funnelchat.com/api/v1/contacts?perPage=5" \
  -H "Authorization: Bearer <id>|fc_live_..." \
  -H "Accept: application/json"

Responde 200 con data, links, meta (según la especificación). Pide el permiso conversations:read.

Un ejemplo de paginaciónCopiar el enlace a esta sección

La respuesta trae data con los elementos de la página, links con los enlaces a otras páginas y meta con los totales. Recortada a lo que importa para paginar (es la de la Guía rápida):

{
  "data": [ … ],
  "links": {
    "first": "https://api.funnelchat.com/api/v1/contacts?perPage=5&page=1",
    "last": "https://api.funnelchat.com/api/v1/contacts?perPage=5&page=88",
    "prev": null,
    "next": "https://api.funnelchat.com/api/v1/contacts?perPage=5&page=2"
  },
  "meta": { "current_page": 1, "last_page": 88, "per_page": 5, "total": 436 }
}

Para pedir la página siguiente, seguí links.next tal cual: conserva perPage y los filtros de tu consulta. Pará cuando links.next sea null.

curl "https://api.funnelchat.com/api/v1/contacts?perPage=5&page=2" \
  -H "Authorization: Bearer <id>|fc_live_..." \
  -H "Accept: application/json"

perPage y page valen para esta ruta; cada ruta dice en su referencia qué parámetros acepta.

Errores comunesCopiar el enlace a esta sección

Cuando el portero o la entrada de la API rechazan una llamada, el cuerpo trae error (un código estable) y message (para personas). Decidí por el código HTTP y por error, no por message. Como toda respuesta, el error trae la cabecera X-Request-Id.

La lista completa, con los demás códigos (422, 429 rate_limited, 500 edge_misconfigured, 503 gate_unavailable, límites por minuto de una ruta), está en Autenticación y permisos.

El id del pedido: X-Request-IdCopiar el enlace a esta sección

Cada respuesta de la API trae la cabecera X-Request-Id, en éxito y en error: también en los rechazos del portero (401, 403, 429, 503) y en los errores de la entrada (404 route_not_found, 500 edge_misconfigured, 502 origin_unreachable).

X-Request-Id: 3f2b8c1e-9a4d-4e7b-8c21-5d6f0a9b1c3e

• Es un UUID distinto para cada pedido.
• Es lo que hay que citar al reportar un problema, junto con la hora aproximada de la llamada: con ese id soporte encuentra la llamada. Guardalo en tus logs junto con el código de respuesta.
• No se puede consultar por el id desde la API. No hay ninguna ruta que devuelva una llamada a partir de su id: sirve para que soporte la encuentre, no para buscarla vos.

Los límites de llamadasCopiar el enlace a esta sección

• accounts y communities: hasta 10.000 llamadas por día por clave en cada una. Al superarlo, la API responde 429 daily_cap_exceeded con Retry-After.
• conversations no tiene tope diario. Lo que se limita son los envíos a WhatsApp, por el número que manda y no por la clave: hasta 60 mensajes por segundo en un número de WhatsApp Cloud, 15 en coexistencia y sin límite por QR; además, 10 por minuto al mismo contacto en lo que sale por WhatsApp Cloud. No hay un límite por minuto por clave ni por cuenta. Ver Ritmo por número.