Guía de inicio rápido de la Public API de Chatfuel

La guía de inicio rápido te lleva de no tener ningún token a una llamada funcional a la Public API de Chatfuel en cinco pasos: crea tu token de API personal, encuentra el ID del bot, crea un usuario virtual, lee contactos con el token del usuario virtual y modifica un contacto. Necesitas el rol Admin en el bot, una terminal con curl y jq, y unos diez minutos.

Paso 1: Crea tu token de API personal

En el panel de Chatfuel, el token de API personal se llama CLI token. Solo lo usas para gestionar usuarios virtuales y otras configuraciones a nivel de cuenta.

1. Inicia sesión en el panel de Chatfuel en panel.chatfuel.com.
2. Abre el menú de la cuenta (tu nombre o avatar) y selecciona CLI token. La página también está disponible directamente en https://panel.chatfuel.com/integration/auth/token.
3. Haz clic en Create token y luego en Copy token.
4. Guarda el token de API personal en un gestor de contraseñas o en un almacén de secretos. Chatfuel muestra el token una sola vez.

Guarda el token de API personal en una variable de entorno para el resto de la guía:

export CHATFUEL_PERSONAL_TOKEN="paste-your-cli-token-here"

Cualquiera que tenga el token de API personal puede actuar como tú en todos los bots a los que tienes acceso. Nunca lo subas a un repositorio ni lo pongas en código del lado del cliente.

Paso 2: Encuentra el ID de tu bot

Cada operación de la Public API funciona dentro de un bot. Lista los bots a los que tu cuenta tiene acceso con el token de API personal:

QUERY='query MyBots {
  currentUser {
    botsV2(first: 50) {
      edges { node { id title } }
    }
  }
}'

jq -n --arg query "$QUERY" '{query: $query}' |
curl -s https://panel.chatfuel.com/graphql \
  -H "Authorization: Bearer $CHATFUEL_PERSONAL_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-

El ID del bot también aparece en la barra de direcciones del panel: es la parte que sigue a /automation/ cuando hay un bot abierto. Guárdalo:

export BOT_ID="your-bot-id"

Paso 3: Crea un usuario virtual

Un usuario virtual es un miembro de un bot que solo usa la API. Recibe su propio token, que usas para todas las demás llamadas. Créalo con la mutación createVirtualUser y el token de API personal:

QUERY='mutation CreateVirtualUser($botID: BotID!) {
  createVirtualUser(
    botID: $botID
    name: "Quickstart integration"
    role: { roleType: Editor, botPermissions: [] }
  ) {
    member { id role { roleTypeV2 } user { id name accountType } }
    authToken
  }
}'

jq -n --arg query "$QUERY" --arg botID "$BOT_ID" \
  '{query: $query, variables: {botID: $botID}}' |
curl -s https://panel.chatfuel.com/graphql \
  -H "Authorization: Bearer $CHATFUEL_PERSONAL_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-

La respuesta contiene el nuevo miembro y su token:

{
  "data": {
    "createVirtualUser": {
      "member": {
        "id": "6f1c…",
        "role": { "roleTypeV2": "Editor" },
        "user": { "id": "6f1b…", "name": "Quickstart integration", "accountType": "Virtual" }
      },
      "authToken": "3c9e…"
    }
  }
}

authToken se muestra solo en esta respuesta. Guárdalo junto con member.id, que necesitarás más adelante para regenerar el token o eliminar el usuario virtual:

export CHATFUEL_VIRTUAL_USER_TOKEN="paste-authToken-here"

El rol puede ser Editor o Agent. Usuarios virtuales explica qué permite cada rol.

Paso 4: Lee contactos con el token del usuario virtual

Cambia al token del usuario virtual y lee el título del bot y los primeros diez contactos:

QUERY='query Contacts($botID: BotID!) {
  bot(id: $botID) {
    title
    contactsConnection(platforms: [whatsapp, instagram, facebook, tiktok, widget], first: 10) {
      edges { node { id name note updatedAt } }
      pageInfo { hasNextPage endCursor }
    }
  }
}'

jq -n --arg query "$QUERY" --arg botID "$BOT_ID" \
  '{query: $query, variables: {botID: $botID}}' |
curl -s https://panel.chatfuel.com/graphql \
  -H "Authorization: Bearer $CHATFUEL_VIRTUAL_USER_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-

Para obtener la página siguiente, pasa pageInfo.endCursor como argumento after. Cómo hacer solicitudes muestra el patrón de paginación completo.

Paso 5: Modifica un contacto

Toma un id de contacto de la respuesta anterior y agrégale una nota con contactSetNote:

export CONTACT_ID="a-contact-id-from-step-4"

QUERY='mutation SetNote($contactID: ContactID!, $note: String) {
  contactSetNote(id: $contactID, note: $note) { id note }
}'

jq -n --arg query "$QUERY" --arg contactID "$CONTACT_ID" --arg note "Synced from CRM" \
  '{query: $query, variables: {contactID: $contactID, note: $note}}' |
curl -s https://panel.chatfuel.com/graphql \
  -H "Authorization: Bearer $CHATFUEL_VIRTUAL_USER_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-

La nota ya aparece en la ficha del contacto en el panel, y el usuario virtual figura entre los miembros del equipo del bot con la etiqueta API. A partir de aquí, explora la referencia de contactos y la referencia de mensajería, o lee sobre tokens y autenticación antes de pasar a producción.

Problemas comunes

"NotEnoughPermissions" al crear un usuario virtual

createVirtualUser solo funciona con el token de API personal de un usuario que tiene el rol Admin en el bot. Esta mutación siempre rechaza el token de un usuario virtual, aunque el usuario virtual exista en el mismo bot.

"VirtualUserRoleNotAllowed"

El rol debe ser Editor o Agent. Los usuarios virtuales no pueden ser Admin ni tener un rol Custom.

"Unauthorized"

Falta el token, está mal escrito o fue revocado, o al encabezado le falta el prefijo Bearer . Envía Authorization: Bearer <token> y comprueba que el token no se haya regenerado mientras tanto.