---
title: "Guía de inicio rápido de la Public API de Chatfuel"
description: "Crea un token de API personal, encuentra el ID de tu bot, crea un usuario virtual y haz tu primera consulta y mutación en la Public API en unos diez minutos."
canonical_url: https://chatfuel.com/es/docs/public-api/quickstart
markdown_url: https://chatfuel.com/es/docs/public-api/quickstart.md
last_updated: 2026-10-06
lang: es
site: https://chatfuel.com/docs
llms_txt: https://chatfuel.com/llms.txt
---

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

Crea un token de API personal, encuentra el ID de tu bot, crea un usuario virtual y haz tu primera consulta y mutación en la Public API en unos diez minutos.

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 [#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:

```bash
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 [#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:

```bash
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:

```bash
export BOT_ID="your-bot-id"
```

## Paso 3: Crea un usuario virtual [#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:

```bash
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:

```json
{
  "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:

```bash
export CHATFUEL_VIRTUAL_USER_TOKEN="paste-authToken-here"
```

El rol puede ser `Editor` o `Agent`. [Usuarios virtuales](https://chatfuel.com/es/docs/public-api/virtual-users) explica qué permite cada rol.

## Paso 4: Lee contactos con el token del usuario virtual [#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:

```bash
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](https://chatfuel.com/es/docs/public-api/requests) muestra el patrón de paginación completo.

## Paso 5: Modifica un contacto [#paso-5-modifica-un-contacto]

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

```bash
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](https://chatfuel.com/es/docs/public-api/contacts) y la [referencia de mensajería](https://chatfuel.com/es/docs/public-api/messaging), o lee sobre [tokens y autenticación](https://chatfuel.com/es/docs/public-api/authentication) antes de pasar a producción.

## Problemas comunes [#problemas-comunes]

### "NotEnoughPermissions" al crear un usuario virtual [#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" [#virtualuserrolenotallowed]

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

### "Unauthorized" [#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.