Contactos

Un contacto es una persona que escribe a un bot en una app de mensajería o en el chat de un sitio web. Los métodos de esta página exportan los contactos de tus bots (por ejemplo, para pasarlos a un CRM), los cuentan y crean un contacto desde tu propio sistema cuando ya conoces el ID de la persona en el canal. Para los contactos en el panel, consulta Contactos.

Puedes recorrer una exportación de dos formas: por páginas (page y count, hasta 500 contactos por solicitud) o por desplazamiento desde el inicio (offset y limit, hasta 1000 contactos por solicitud). getNumberOfContacts indica cuántos contactos cumplen los filtros.

Los métodos devuelven solo los contactos de tus propios bots. Los contactos creados al probar un bot en la vista previa no se incluyen en exportaciones ni recuentos.

Campos del contacto

Todos los métodos que devuelven contactos, aquí y en la página Referidos, los devuelven con la misma estructura.

Campo	Tipo	Descripción
`id`	número	ID del contacto
`bot_id`	número	ID del bot
`phone`	cadena o `null`	Número de teléfono, si el contacto lo compartió o se definió mediante la API
`email`	cadena o `null`	Email
`name`	cadena	Nombre
`address`	cadena o `null`	Dirección
`messenger`	cadena	De dónde viene el contacto: `telegram`, `max`, `viber`, `vk` o `web` (chat del sitio web)
`utm`	objeto	Variables del contacto cuyo nombre empieza por `utm_`: `{"utm_source": "…"}`. Si no hay ninguna, un array vacío `[]`
`avatar`	cadena o `null`	Enlace a la foto del contacto. El enlace a un archivo del almacenamiento es temporal: guarda el archivo, no el enlace
`telegram_id`	cadena	ID del usuario en Telegram. Solo contactos de Telegram
`telegram_username`	cadena o `null`	Nombre de usuario de Telegram sin `@`. Solo contactos de Telegram
`max_user_id`	número	ID del usuario en MAX. Solo contactos de MAX
`max_username`	cadena o `null`	Nombre de usuario en MAX. Solo contactos de MAX
`vk_user_id`	número o `null`	ID del usuario en VK. Está en todos los contactos; `null` en los que no son de VK
`viber_id`	cadena	ID del usuario en Viber. Solo contactos de Viber
`created_at`	cadena	Cuándo apareció el contacto, ISO 8601 en UTC
`unsubscribed_at`	cadena o `null`	Cuándo el contacto se dio de baja del bot; `null` significa que está suscrito
`tags`	array de cadenas	Etiquetas del contacto
`variables`	array de objetos	Variables del contacto

Cada variable de variables es un objeto:

Campo	Descripción
`id`	ID de la variable dentro del contacto
`name`	Nombre de la variable
`value`	Valor
`type`	Qué contiene el valor: `0`, texto; `1`, imagen; `2`, documento; `3`, audio; `4`, video. En los archivos multimedia, `value` contiene un enlace al archivo, que el método decodeShortLink resuelve
`schema_id`, `deletable`, `payload`	Campos internos

Para las etiquetas y variables en el panel, consulta Etiquetas y variables.

getContacts

Devuelve los contactos de tus bots, por páginas (20 por página por defecto) o por desplazamiento desde el inicio.

GETPOSThttps://watbot.org/es/api/v1/getContacts

Parámetro	Tipo	Obligatorio	Descripción
`bot_id`	número	no	Solo los contactos de este bot. Sin él, los contactos de todos tus bots
`count`	número	no	Contactos por página: de 1 a 500. Por defecto, 20
`page`	número	no	Número de página, a partir de 1. Por defecto, 1
`offset`	número	no	Cuántos contactos omitir desde el inicio, a partir de 0. Activa la paginación por desplazamiento
`limit`	número	no	Cuántos contactos devolver en la paginación por desplazamiento: de 1 a 1000. Por defecto, 100. También activa la paginación por desplazamiento
`date_from`	número	no	Contactos que aparecieron en este momento o después. Tiempo Unix en segundos
`date_to`	número	no	Contactos que aparecieron en este momento o antes. Tiempo Unix en segundos
`with`	cadena	no	Se acepta por compatibilidad, p. ej. `variables`. No cambia nada: las etiquetas y variables siempre van en la respuesta

Los contactos se ordenan por id ascendente, tanto por páginas como por desplazamiento. Si se pasa offset o limit, se usa la paginación por desplazamiento y se ignoran page y count.

Por páginas

Solicitud

curl -X POST "https://watbot.org/es/api/v1/getContacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 12345, "count": 2, "date_from": 1758931200}'

Respuesta 200

{
  "data": [
    {
      "id": 4815162,
      "bot_id": 12345,
      "phone": "15550100123",
      "email": null,
      "name": "Emily Johnson",
      "address": null,
      "messenger": "telegram",
      "utm": {"utm_source": "newsletter"},
      "avatar": null,
      "telegram_id": "123456789",
      "telegram_username": "emily_j",
      "vk_user_id": null,
      "created_at": "2026-09-28T07:41:12+00:00",
      "unsubscribed_at": null,
      "tags": ["ordered"],
      "variables": [
        {"id": 17590475010001, "name": "utm_source", "value": "newsletter", "type": 0, "schema_id": null, "deletable": false, "payload": null},
        {"id": 17590475820003, "name": "city", "value": "Austin", "type": 0, "schema_id": null, "deletable": false, "payload": null}
      ]
    },
    {
      "id": 4815170,
      "bot_id": 12345,
      "phone": null,
      "email": null,
      "name": "Michael Brown",
      "address": null,
      "messenger": "vk",
      "utm": [],
      "avatar": null,
      "vk_user_id": 700123456,
      "created_at": "2026-09-29T15:02:47+00:00",
      "unsubscribed_at": null,
      "tags": [],
      "variables": []
    }
  ],
  "links": {
    "first": "https://watbot.org/es/api/v1/getContacts?page=1",
    "last": "https://watbot.org/es/api/v1/getContacts?page=38",
    "prev": null,
    "next": "https://watbot.org/es/api/v1/getContacts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 38,
    "links": […],
    "path": "https://watbot.org/es/api/v1/getContacts",
    "per_page": 2,
    "to": 2,
    "total": 75
  }
}

meta.total es el número total de contactos que cumplen los filtros, y meta.last_page, el número de la última página. Para exportarlo todo, pide páginas hasta que links.next sea null. Las URL de links no llevan ninguno de tus parámetros salvo page: envía bot_id, count y las fechas de nuevo en cada solicitud.
Los contactos nuevos quedan al final de la exportación: ordenar por id evita que las páginas se desplacen. Para que la exportación no crezca mientras la recorres, limítala con date_to.
Un bot_id de un bot que no es tuyo o que no existe no provoca un error: la lista simplemente queda vacía.

Por desplazamiento

Solicitud de la segunda centena de contactos del bot:

Solicitud

curl -X POST "https://watbot.org/es/api/v1/getContacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 12345, "limit": 100, "offset": 100}'

Respuesta 200

{
  "data": [
    {
      "id": 4815162,
      "bot_id": 12345,
      "phone": "15550100123",
      "email": null,
      "name": "Emily Johnson",
      "address": null,
      "messenger": "telegram",
      "utm": [],
      "avatar": null,
      "telegram_id": "123456789",
      "telegram_username": "emily_j",
      "vk_user_id": null,
      "created_at": "2026-09-28T07:41:12+00:00",
      "unsubscribed_at": null,
      "tags": ["ordered"],
      "variables": [
        {"id": 17590475820003, "name": "city", "value": "Austin", "type": 0, "schema_id": null, "deletable": false, "payload": null}
      ]
    }
  ],
  "meta": {
    "offset": 100,
    "limit": 100,
    "total": 101
  }
}

meta.total es el número total de contactos que cumplen los filtros. La exportación está completa cuando data contiene menos contactos que limit, o cuando offset + limit alcanza meta.total.
Para el primer lote, pasa offset 0 u omite offset.

getNumberOfContacts

Cuenta los contactos de tus bots, con los mismos filtros que getContacts.

GETPOSThttps://watbot.org/es/api/v1/getNumberOfContacts

Parámetro	Tipo	Obligatorio	Descripción
`bot_id`	número	no	Solo los contactos de este bot. Sin él, todos tus bots
`date_from`	número	no	Contactos que aparecieron en este momento o después. Tiempo Unix en segundos
`date_to`	número	no	Contactos que aparecieron en este momento o antes. Tiempo Unix en segundos

Solicitud

curl "https://watbot.org/es/api/v1/getNumberOfContacts?bot_id=12345" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Respuesta 200

{
  "count": 1284
}

El número está en el campo count del nivel superior, sin el contenedor data.

createOrUpdateContact

Crea un contacto en un bot o actualiza uno existente. El contacto se busca en el bot por su ID en el canal: telegram_id, max_id, vk_id o viber_id. Si se encuentra, se actualizan sus datos; si no, se crea un contacto nuevo.

GETPOSThttps://watbot.org/es/api/v1/createOrUpdateContact

Parámetro	Tipo	Obligatorio	Descripción
`bot_id`	número	sí	ID de tu bot
`messenger`	cadena	sí	Canal del contacto: `telegram`, `max`, `viber` o `vk`
`name`	cadena	sí	Nombre del contacto. Reemplaza el nombre anterior en cada llamada
`telegram_id`	número	para `telegram`	ID del usuario en Telegram
`telegram_username`	cadena	no	Nombre de usuario de Telegram, hasta 255 caracteres
`max_id`	número	para `max`	ID del usuario en MAX. También se puede pasar como `max_user_id`, el nombre que tiene en la respuesta
`max_username`	cadena	no	Nombre de usuario en MAX, hasta 255 caracteres
`vk_id`	número	para `vk`	ID del usuario en VK. También se puede pasar como `vk_user_id`, el nombre que tiene en la respuesta
`viber_id`	cadena	para `viber`	ID del usuario en Viber, hasta 255 caracteres
`phone`	cadena	no	Teléfono en formato internacional: `+` seguido de dígitos, de 9 a 16 caracteres con el signo más, `+15550100123`. Se guarda en dígitos, sin `+`; `null` equivale a no pasar teléfono
`email`	cadena	no	Email
`address`	cadena	no	Dirección, hasta 255 caracteres
`tags`	array de cadenas	no	Etiquetas, hasta 100, cada una de hasta 255 caracteres. Reemplazan todas las etiquetas del contacto

Solicitud

curl -X POST "https://watbot.org/es/api/v1/createOrUpdateContact" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": 12345,
    "messenger": "telegram",
    "telegram_id": 123456789,
    "telegram_username": "emily_j",
    "name": "Emily Johnson",
    "phone": "+15550100123",
    "email": "emily@example.com",
    "tags": ["client", "from CRM"]
  }'

Respuesta 201

{
  "data": {
    "id": 4815162,
    "bot_id": 12345,
    "phone": "15550100123",
    "email": "emily@example.com",
    "name": "Emily Johnson",
    "address": null,
    "messenger": "telegram",
    "utm": [],
    "avatar": null,
    "telegram_id": "123456789",
    "telegram_username": "emily_j",
    "vk_user_id": null,
    "created_at": "2026-10-03T09:15:42+00:00",
    "unsubscribed_at": null,
    "tags": ["client", "from CRM"],
    "variables": []
  }
}

Respuesta 404

{
  "message": "Bot not found",
  "errors": {
    "bot_id": ["Bot not found"]
  }
}

El estado 201 significa que se creó el contacto, y 200, que se actualizó uno existente.

Qué cambia en un contacto existente. name, siempre. email, address, phone, telegram_username y max_username, solo si se pasan y no están vacíos: este método no puede vaciarlos. tags, si se pasan, reemplazan todo el conjunto de etiquetas; un array vacío [] quita todas las etiquetas. El método no toca las variables del contacto.
Un contacto nuevo aparece en la lista de contactos del bot con el primer mensaje «Created from API» y aumenta el número de suscriptores del bot. El flujo del bot no se inicia y no se envía nada al contacto.
El teléfono se guarda en dígitos, sin +, igual que lo guardan los bloques del bot. phone en la respuesta tampoco lleva +.

Errores del método (los generales están en Errores):

Código	Cuándo	Respuesta
`404`	Ninguno de tus bots tiene este `bot_id`: no existe o pertenece a otra cuenta	`{"message": "…", "errors": {"bot_id": ["…"]}}`
`422`	Falta el ID del canal elegido, o el formato del teléfono o del email no es válido	`{"message": "…", "errors": {…}}`

Contactos#

Campos del contacto#

getContacts#

Por páginas#

Por desplazamiento#

getNumberOfContacts#

createOrUpdateContact#

Contactos

Campos del contacto

getContacts

Por páginas

Por desplazamiento

getNumberOfContacts

createOrUpdateContact