Referencia

Todas las operaciones de la API de AdSmartBot, con lo que aceptan, lo que devuelven y sus errores. Todas cuelgan de https://panel.adsmartbot.com/api/v1.

Tu clave de acceso, para «Probar»

Cuenta

GET/me

La clave de acceso con que llamas, su cuenta y su marca

Es lo que Zapier y Make llaman «probar la conexión». Responde también con la cuenta en pago pendiente.

Cualquier clave válida · operationId getMe

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/me" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

objectsiempre "api_key_info"obligatorio
keyobjetoobligatorio
Ver sus 6 datos
- idtextoobligatorio
  Identificador (uuid).
- nametextoobligatorio
- prefixtextoobligatorio
- modeuno de estos valoresobligatorio
  livetest
- scopeslista de textoobligatorio
- expires_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
accountobjetoobligatorio
Ver sus 2 datos
- idtextoobligatorio
  Identificador (uuid).
- nametextoobligatorio
brandobjetoobligatorio
Ver sus 2 datos
- nametextoobligatorio
- domaintextoobligatorio
api_versionsiempre "v1"obligatorio

Ver una respuesta de ejemplo

{
  "object": "api_key_info",
  "key": {
    "id": "0f1e2d3c-4b5a-4968-8776-65a4b3c2d1e0",
    "name": "Tienda Shopify",
    "prefix": "ak_live_7Hq2",
    "mode": "live",
    "scopes": [
      "contacts:read",
      "contacts:write",
      "messages:send",
      "flows:run"
    ],
    "expires_at": null
  },
  "account": {
    "id": "5b3e1c2a-7d4f-4a8b-9c1d-2e3f4a5b6c7d",
    "name": "Peluquería Ana"
  },
  "brand": {
    "name": "AdSmartBot",
    "domain": "panel.adsmartbot.com"
  },
  "api_version": "v1"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/me

GET/account

Los datos de la cuenta y el estado de su plan

Responde también con la cuenta en pago pendiente: así tu sistema puede decir por qué lo demás responde 402.

Permiso account:read («Ver la cuenta») · operationId getAccount

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/account" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "account"obligatorio
nametextoobligatorio
timezonetextoobligatorio
countrytexto o nullobligatorio
País de la cuenta, en dos letras. Nulo si la cuenta aún no lo ha elegido.
localetextoobligatorio
websitetexto o nullobligatorio
planobjetoobligatorio
Ver sus 5 datos
- codetextoobligatorio
- nametextoobligatorio
- statusuno de estos valoresobligatorio
  trialactivepast_duesuspended
- trial_ends_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
- paid_untiltexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
contacts_countnúmero enteroobligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "5b3e1c2a-7d4f-4a8b-9c1d-2e3f4a5b6c7d",
  "object": "account",
  "name": "Peluquería Ana",
  "timezone": "America/Bogota",
  "country": "CO",
  "locale": "es",
  "website": "https://peluqueriaana.com",
  "plan": {
    "code": "pro",
    "name": "Pro",
    "status": "active",
    "trial_ends_at": null,
    "paid_until": "2026-10-26T05:00:00.000Z"
  },
  "contacts_count": 1832,
  "created_at": "2026-03-02T14:10:00.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/account

GET/account/usage

Lo que usa la cuenta frente a su plan, y el uso de la API de hoy

Contactos, personas del equipo, canales y correos frente a lo que permite el plan; y de la API: peticiones y errores de hoy, los límites de ritmo y las plantillas de hoy frente al tope diario (el día es el de la zona horaria de la cuenta).

Permiso account:read («Ver la cuenta») · operationId getAccountUsage

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/account/usage" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

objectsiempre "account_usage"obligatorio
contactsobjetoobligatorio
Ver sus 3 datos
- usednúmeroobligatorio
- limitnúmeroobligatorio
- counts_createdsí/no (booleano)obligatorio
  En la prueba gratis cuentan los contactos creados, también los que ya se borraron.
membersobjetoobligatorio
Ver sus 2 datos
- usednúmeroobligatorio
- limitnúmeroobligatorio
channelslista de objetoobligatorio
Ver sus 3 datos
- typetextoobligatorio
- usednúmero enteroobligatorio
- limitnúmero enteroobligatorio
emailsobjetoobligatorio
Ver sus 5 datos
- usednúmeroobligatorio
- limitnúmero o nullobligatorio
  Los correos del mes. Nulo = sin límite (una cuenta con los correos sin tope).
- trialsí/no (booleano)obligatorio
- period_starttextoobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
- renews_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
apiobjetoobligatorio
Ver sus 4 datos
- requests_todaynúmero enteroobligatorio
- errors_todaynúmero enteroobligatorio
- rate_limitsobjetoobligatorio
  Ver sus 4 datos
  - per_key_per_minutenúmero enteroobligatorio
  - per_key_per_secondnúmero enteroobligatorio
  - per_account_per_minutenúmero enteroobligatorio
  - sends_per_minutenúmero enteroobligatorio
- templates_todayobjetoobligatorio
  Ver sus 3 datos
  - usednúmeroobligatorio
  - limitnúmeroobligatorio
  - resets_attextoobligatorio
    Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "object": "account_usage",
  "contacts": {
    "used": 1832,
    "limit": 10000,
    "counts_created": false
  },
  "members": {
    "used": 3,
    "limit": 5
  },
  "channels": [
    {
      "type": "whatsapp",
      "used": 1,
      "limit": 1
    },
    {
      "type": "webchat",
      "used": 1,
      "limit": 1
    }
  ],
  "emails": {
    "used": 320,
    "limit": 3000,
    "trial": false,
    "period_start": "2026-09-16T05:00:00.000Z",
    "renews_at": "2026-10-16T05:00:00.000Z"
  },
  "api": {
    "requests_today": 412,
    "errors_today": 3,
    "rate_limits": {
      "per_key_per_minute": 120,
      "per_key_per_second": 20,
      "per_account_per_minute": 300,
      "sends_per_minute": 120
    },
    "templates_today": {
      "used": 38,
      "limit": 1000,
      "resets_at": "2026-09-28T05:00:00.000Z"
    }
  }
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/account/usage

GET/channels

Los números de WhatsApp y los chats web de la cuenta, con su estado

Nunca devuelve el token de un canal. last_error dice por qué un canal no está conectado. automations_enabled es falso si en Configuración → Canales se apagaron sus automatizaciones: ese canal se atiende solo a mano y POST /messages responde 409 channel_not_available si lo eliges.

Permiso account:read («Ver la cuenta») · operationId listChannels

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/channels" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

idtextoobligatorio
Identificador (uuid).
objectsiempre "channel"obligatorio
typetextoobligatorio
nametexto o nullobligatorio
phonetexto o nullobligatorio
Teléfono en E.164, con «+».
statusuno de estos valoresobligatorio
connecteddisconnectederror
last_errortexto o nullobligatorio
automations_enabledsí/no (booleano)obligatorio
Falso si en Configuración → Canales se apagaron las automatizaciones de este canal: se atiende solo a mano y la API no escribe por él (409 channel_not_available).
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "object": "channel",
      "type": "whatsapp",
      "name": "Peluquería Ana",
      "phone": "+573001234567",
      "status": "connected",
      "last_error": null,
      "automations_enabled": true,
      "created_at": "2026-03-02T14:20:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/channels

GET/integrations

Lo que la cuenta tiene conectado: proveedores de IA, Google, conversiones de Meta y canales

Sin claves ni tokens: solo qué está conectado y si funciona.

Permiso account:read («Ver la cuenta») · operationId listIntegrations

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/integrations" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

objectsiempre "integrations"obligatorio
ai_providerslista de objetoobligatorio
Ver sus 4 datos
- providertextoobligatorio
- statusuno de estos valoresobligatorio
  okerrorunchecked
- last_errortexto o nullobligatorio
- prioritynúmero enteroobligatorio
googleobjetoobligatorio
Ver sus 4 datos
- connectedsí/no (booleano)obligatorio
- emailtexto o nullobligatorio
- calendarsí/no (booleano)obligatorio
- sheetssí/no (booleano)obligatorio
email_senderslista de objetoobligatorio
Ver sus 6 datos
- idtextoobligatorio
  Identificador (uuid).
- addresstextoobligatorio
- nametextoobligatorio
- kindtextoobligatorio
- statustextoobligatorio
- defaultsí/no (booleano)obligatorio
meta_conversionsobjetoobligatorio
Ver sus 1 datos
- connectedsí/no (booleano)obligatorio
channelslista de objetoobligatorio
Ver sus 9 datos
- idtextoobligatorio
  Identificador (uuid).
- objectsiempre "channel"obligatorio
- typetextoobligatorio
- nametexto o nullobligatorio
- phonetexto o nullobligatorio
  Teléfono en E.164, con «+».
- statusuno de estos valoresobligatorio
  connecteddisconnectederror
- last_errortexto o nullobligatorio
- automations_enabledsí/no (booleano)obligatorio
  Falso si en Configuración → Canales se apagaron las automatizaciones de este canal: se atiende solo a mano y la API no escribe por él (409 channel_not_available).
- created_attextoobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "object": "integrations",
  "ai_providers": [
    {
      "provider": "openai",
      "status": "ok",
      "last_error": null,
      "priority": 0
    }
  ],
  "google": {
    "connected": true,
    "email": "ana@peluqueriaana.com",
    "calendar": true,
    "sheets": false
  },
  "email_senders": [
    {
      "id": "7a6b5c4d-3e2f-4a1b-8c9d-0e1f2a3b4c5d",
      "address": "hola@peluqueriaana.com",
      "name": "Peluquería Ana",
      "kind": "dominio",
      "status": "listo",
      "default": true
    }
  ],
  "meta_conversions": {
    "connected": false
  },
  "channels": [
    {
      "id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "object": "channel",
      "type": "whatsapp",
      "name": "Peluquería Ana",
      "phone": "+573001234567",
      "status": "connected",
      "last_error": null,
      "automations_enabled": true,
      "created_at": "2026-03-02T14:20:00.000Z"
    }
  ]
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/integrations

GET/members

Las personas del equipo

El id de cada persona es el que usa la acción assign. available sale null hasta que exista el estado «Disponible».

Permiso account:read («Ver la cuenta») · operationId listMembers

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/members" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

idtextoobligatorio
Identificador (uuid).
objectsiempre "member"obligatorio
nametextoobligatorio
emailtexto o nullobligatorio
roleuno de estos valoresobligatorio
owneradminagent
avatar_urltexto o nullobligatorio
last_active_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
availablenuloobligatorio

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "id": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a",
      "object": "member",
      "name": "Laura Pérez",
      "email": "laura@peluqueriaana.com",
      "role": "admin",
      "avatar_url": null,
      "last_active_at": "2026-09-26T18:02:00.000Z",
      "available": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/members

Contactos

GET/contacts

Lista de contactos con cursor, sin datos personales en la dirección

Para sincronizar con otro CRM: ?updated_since=…&sort=updated_at&order=asc y recorre hasta has_more: false; la próxima vez pide desde un minuto antes del updated_at más alto que viste (el mismo contacto puede salir dos veces: se reconoce por su id). Para buscar por teléfono, correo o un campo usa POST /contacts/search.

Permiso contacts:read («Ver contactos») · operationId listContacts

Parámetros

limitnúmero entero · en la dirección
De 1 a 100. Por defecto, 25.
cursortexto · en la dirección
El next_cursor de la página anterior.
tagtexto o lista de texto · en la dirección
Nombre o id de una etiqueta. Se puede repetir (?tag=VIP&tag=Nuevo): tienen que estar todas.
channeluno de estos valores · en la dirección
originuno de estos valores · en la dirección
created_sincetexto · en la dirección
Fecha y hora en ISO 8601 con zona horaria.
created_beforetexto · en la dirección
Fecha y hora en ISO 8601 con zona horaria.
updated_sincetexto · en la dirección
Incluye el instante que pasas (>=). Pide desde un minuto antes de lo último que viste.
broadcasts_subscribeduno de estos valores · en la dirección
true o false.
blockeduno de estos valores · en la dirección
true o false.
sortuno de estos valores · en la dirección
Por defecto, created_at. Con updated_at no salen los que cambiaron hace menos de 60 segundos.
orderuno de estos valores · en la dirección
Por defecto, desc.

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/contacts" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

idtextoobligatorio
Identificador (uuid).
objectsiempre "contact"obligatorio
channeltextoobligatorio
El canal por el que existe este contacto: whatsapp, webchat, messenger o instagram.
first_nametexto o nullobligatorio
last_nametexto o nullobligatorio
full_nametexto o nullobligatorio
phonetexto o nullobligatorio
Teléfono en E.164, con «+».
emailtexto o nullobligatorio
email_verifiedsí/no (booleano)obligatorio
whatsappobjeto o nullobligatorio
Ver sus 3 datos
- wa_idtexto o nullobligatorio
- bsuidtexto o nullobligatorio
- usernametexto o nullobligatorio
profile_pic_urltexto o nullobligatorio
localetexto o nullobligatorio
timezonetexto o nullobligatorio
originuno de estos valores o nullobligatorio
addirect_messagewebchatimportcallphone_appexternal_system
tagslista de objetoobligatorio
Ver sus 2 datos
- idtextoobligatorio
  Identificador (uuid).
- nametextoobligatorio
fieldsobjetoobligatorio
Los campos con valor, cada uno en su tipo: número, booleano, «AAAA-MM-DD», lista…
broadcasts_subscribedsí/no (booleano)obligatorio
broadcasts_opt_outobjeto o nullobligatorio
Ver sus 2 datos
- byuno de estos valoresobligatorio
  contactteamflowapi
- attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_opt_inobjeto o nullobligatorio
Ver sus 3 datos
- statusuno de estos valoresobligatorio
  grantedrevoked
- sourcetextoobligatorio
- captured_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
email_unsubscribedsí/no (booleano)obligatorio
blockedsí/no (booleano)obligatorio
interactions_countnúmero enteroobligatorio
has_writtensí/no (booleano)obligatorio
Si escribió alguna vez. Si no, una plantilla necesita su permiso de WhatsApp.
last_inbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
last_outbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_windowslista de objetoobligatorio
La ventana de 24 horas con cada número de WhatsApp del negocio.
Ver sus 3 datos
- channel_idtextoobligatorio
  Identificador (uuid).
- opensí/no (booleano)obligatorio
- closes_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
      "object": "contact",
      "channel": "whatsapp",
      "first_name": "Ana",
      "last_name": "Gómez",
      "full_name": "Ana Gómez",
      "phone": "+573001234567",
      "email": "ana@correo.com",
      "email_verified": false,
      "whatsapp": {
        "wa_id": "573001234567",
        "bsuid": null,
        "username": null
      },
      "profile_pic_url": null,
      "locale": null,
      "timezone": "America/Bogota",
      "origin": "external_system",
      "tags": [
        {
          "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
          "name": "Lead web"
        }
      ],
      "fields": {
        "Ciudad": "Cali",
        "Talla": "M",
        "Cumpleaños": "1990-05-14",
        "Aceptó los términos": true
      },
      "broadcasts_subscribed": true,
      "broadcasts_opt_out": null,
      "whatsapp_opt_in": {
        "status": "granted",
        "source": "form",
        "captured_at": "2026-09-26T19:02:00.000Z"
      },
      "email_unsubscribed": false,
      "blocked": false,
      "interactions_count": 12,
      "has_written": true,
      "last_inbound_at": "2026-09-26T14:40:00.000Z",
      "last_outbound_at": "2026-09-26T14:41:10.000Z",
      "whatsapp_windows": [
        {
          "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
          "open": true,
          "closes_at": "2026-09-27T14:40:00.000Z"
        }
      ],
      "created_at": "2026-09-01T10:00:00.000Z",
      "updated_at": "2026-09-26T14:41:10.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJvIjoiMjAyNi0wOS0yNlQxNDo0MToxMC4xMjM0NTZaIiwiaSI6ImE0ZjJjMGRlIn0.Vq1l6kQ"
}

Errores posibles

400 date_without_timezoneLa fecha «…» tiene que llevar zona horaria, por ejemplo 2026-09-27T10:00:00-05:00.
400 invalid_cursorEl cursor no es válido o cambiaron los filtros. Empieza la lista de nuevo.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts

POST/contacts/search

Buscar contactos por teléfono, correo, el valor de un campo o un texto

El dato va en el cuerpo y nunca en la dirección: las direcciones quedan en registros que nadie controla. El teléfono se busca en todas sus formas (México 521…, Argentina 549…, Brasil con y sin el noveno dígito). Un mismo cliente por WhatsApp y por el chat web son dos contactos: la búsqueda puede devolver los dos.

Permiso contacts:read («Ver contactos») · operationId searchContacts

Cuerpo (JSON)

phonetexto
Teléfono con el indicativo del país. Se aceptan «+», espacios y guiones.
emailtexto
fieldobjeto
Ver sus 2 datos
- keytextoobligatorio
- valuetexto o número o sí/no (booleano)obligatorio
querytexto
Contiene, en el nombre, el teléfono o el correo.
limitnúmero entero
cursortexto

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/contacts/search" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+57 300 123 4567"}'

Responde 200: una lista; cada elemento de data trae

idtextoobligatorio
Identificador (uuid).
objectsiempre "contact"obligatorio
channeltextoobligatorio
El canal por el que existe este contacto: whatsapp, webchat, messenger o instagram.
first_nametexto o nullobligatorio
last_nametexto o nullobligatorio
full_nametexto o nullobligatorio
phonetexto o nullobligatorio
Teléfono en E.164, con «+».
emailtexto o nullobligatorio
email_verifiedsí/no (booleano)obligatorio
whatsappobjeto o nullobligatorio
Ver sus 3 datos
- wa_idtexto o nullobligatorio
- bsuidtexto o nullobligatorio
- usernametexto o nullobligatorio
profile_pic_urltexto o nullobligatorio
localetexto o nullobligatorio
timezonetexto o nullobligatorio
originuno de estos valores o nullobligatorio
addirect_messagewebchatimportcallphone_appexternal_system
tagslista de objetoobligatorio
Ver sus 2 datos
- idtextoobligatorio
  Identificador (uuid).
- nametextoobligatorio
fieldsobjetoobligatorio
Los campos con valor, cada uno en su tipo: número, booleano, «AAAA-MM-DD», lista…
broadcasts_subscribedsí/no (booleano)obligatorio
broadcasts_opt_outobjeto o nullobligatorio
Ver sus 2 datos
- byuno de estos valoresobligatorio
  contactteamflowapi
- attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_opt_inobjeto o nullobligatorio
Ver sus 3 datos
- statusuno de estos valoresobligatorio
  grantedrevoked
- sourcetextoobligatorio
- captured_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
email_unsubscribedsí/no (booleano)obligatorio
blockedsí/no (booleano)obligatorio
interactions_countnúmero enteroobligatorio
has_writtensí/no (booleano)obligatorio
Si escribió alguna vez. Si no, una plantilla necesita su permiso de WhatsApp.
last_inbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
last_outbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_windowslista de objetoobligatorio
La ventana de 24 horas con cada número de WhatsApp del negocio.
Ver sus 3 datos
- channel_idtextoobligatorio
  Identificador (uuid).
- opensí/no (booleano)obligatorio
- closes_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
      "object": "contact",
      "channel": "whatsapp",
      "first_name": "Ana",
      "last_name": "Gómez",
      "full_name": "Ana Gómez",
      "phone": "+573001234567",
      "email": "ana@correo.com",
      "email_verified": false,
      "whatsapp": {
        "wa_id": "573001234567",
        "bsuid": null,
        "username": null
      },
      "profile_pic_url": null,
      "locale": null,
      "timezone": "America/Bogota",
      "origin": "external_system",
      "tags": [
        {
          "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
          "name": "Lead web"
        }
      ],
      "fields": {
        "Ciudad": "Cali",
        "Talla": "M",
        "Cumpleaños": "1990-05-14",
        "Aceptó los términos": true
      },
      "broadcasts_subscribed": true,
      "broadcasts_opt_out": null,
      "whatsapp_opt_in": {
        "status": "granted",
        "source": "form",
        "captured_at": "2026-09-26T19:02:00.000Z"
      },
      "email_unsubscribed": false,
      "blocked": false,
      "interactions_count": 12,
      "has_written": true,
      "last_inbound_at": "2026-09-26T14:40:00.000Z",
      "last_outbound_at": "2026-09-26T14:41:10.000Z",
      "whatsapp_windows": [
        {
          "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
          "open": true,
          "closes_at": "2026-09-27T14:40:00.000Z"
        }
      ],
      "created_at": "2026-09-01T10:00:00.000Z",
      "updated_at": "2026-09-26T14:41:10.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

400 invalid_cursorEl cursor no es válido o cambiaron los filtros. Empieza la lista de nuevo.
400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 invalid_phoneEl teléfono no es válido. Escríbelo con el indicativo del país, por ejemplo +57 300 123 4567.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/search

GET/contacts/{id}

Un contacto

include (sus conversaciones, oportunidades, citas y secuencias en la misma petición) llega en la próxima versión: hoy responde 400.

Permiso contacts:read («Ver contactos») · operationId getContact

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
includetexto · en la dirección
Llega en la próxima versión.

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "contact"obligatorio
channeltextoobligatorio
El canal por el que existe este contacto: whatsapp, webchat, messenger o instagram.
first_nametexto o nullobligatorio
last_nametexto o nullobligatorio
full_nametexto o nullobligatorio
phonetexto o nullobligatorio
Teléfono en E.164, con «+».
emailtexto o nullobligatorio
email_verifiedsí/no (booleano)obligatorio
whatsappobjeto o nullobligatorio
Ver sus 3 datos
- wa_idtexto o nullobligatorio
- bsuidtexto o nullobligatorio
- usernametexto o nullobligatorio
profile_pic_urltexto o nullobligatorio
localetexto o nullobligatorio
timezonetexto o nullobligatorio
originuno de estos valores o nullobligatorio
addirect_messagewebchatimportcallphone_appexternal_system
tagslista de objetoobligatorio
Ver sus 2 datos
- idtextoobligatorio
  Identificador (uuid).
- nametextoobligatorio
fieldsobjetoobligatorio
Los campos con valor, cada uno en su tipo: número, booleano, «AAAA-MM-DD», lista…
broadcasts_subscribedsí/no (booleano)obligatorio
broadcasts_opt_outobjeto o nullobligatorio
Ver sus 2 datos
- byuno de estos valoresobligatorio
  contactteamflowapi
- attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_opt_inobjeto o nullobligatorio
Ver sus 3 datos
- statusuno de estos valoresobligatorio
  grantedrevoked
- sourcetextoobligatorio
- captured_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
email_unsubscribedsí/no (booleano)obligatorio
blockedsí/no (booleano)obligatorio
interactions_countnúmero enteroobligatorio
has_writtensí/no (booleano)obligatorio
Si escribió alguna vez. Si no, una plantilla necesita su permiso de WhatsApp.
last_inbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
last_outbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_windowslista de objetoobligatorio
La ventana de 24 horas con cada número de WhatsApp del negocio.
Ver sus 3 datos
- channel_idtextoobligatorio
  Identificador (uuid).
- opensí/no (booleano)obligatorio
- closes_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "object": "contact",
  "channel": "whatsapp",
  "first_name": "Ana",
  "last_name": "Gómez",
  "full_name": "Ana Gómez",
  "phone": "+573001234567",
  "email": "ana@correo.com",
  "email_verified": false,
  "whatsapp": {
    "wa_id": "573001234567",
    "bsuid": null,
    "username": null
  },
  "profile_pic_url": null,
  "locale": null,
  "timezone": "America/Bogota",
  "origin": "external_system",
  "tags": [
    {
      "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "name": "Lead web"
    }
  ],
  "fields": {
    "Ciudad": "Cali",
    "Talla": "M",
    "Cumpleaños": "1990-05-14",
    "Aceptó los términos": true
  },
  "broadcasts_subscribed": true,
  "broadcasts_opt_out": null,
  "whatsapp_opt_in": {
    "status": "granted",
    "source": "form",
    "captured_at": "2026-09-26T19:02:00.000Z"
  },
  "email_unsubscribed": false,
  "blocked": false,
  "interactions_count": 12,
  "has_written": true,
  "last_inbound_at": "2026-09-26T14:40:00.000Z",
  "last_outbound_at": "2026-09-26T14:41:10.000Z",
  "whatsapp_windows": [
    {
      "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "open": true,
      "closes_at": "2026-09-27T14:40:00.000Z"
    }
  ],
  "created_at": "2026-09-01T10:00:00.000Z",
  "updated_at": "2026-09-26T14:41:10.000Z"
}

Errores posibles

400 invalid_parameterEl dato «…» no es válido: revisa su formato.
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}

POST/contacts

Crear un contacto, o encontrar el que ya tiene ese teléfono

Busca por teléfono entre tus contactos de WhatsApp, en todas sus formas. Si no existe lo crea (responde 201) con el origen «otro sistema»; si existe, if_exists decide (responde 200). actions corre después, cada una con su permiso, y actions_result dice cómo le fue a cada una. En la prueba gratis el tope de contactos cuenta los creados, también los que ya se borraron.

Permiso contacts:write («Crear y editar contactos») · operationId createContact · acepta Idempotency-Key

Parámetros

Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

phonetexto
Teléfono con el indicativo del país. Se aceptan «+», espacios y guiones.
emailtexto o null
first_nametexto o null
last_nametexto o null
timezonetexto o null
Zona horaria IANA.
tagslista de texto
Etiquetas por nombre o por id.
create_missing_tagssí/no (booleano)
Crear las etiquetas de tags que no existan (por nombre). Por defecto, sí.
fieldsobjeto
Los campos por su clave, cada uno con su valor. null vacía el campo.
broadcasts_subscribedsí/no (booleano)
consentobjeto
Obligatorio con broadcasts_subscribed: true. La prueba de que aceptó la publicidad.
Ver sus 3 datos
- sourceuno de estos valoresobligatorio
  formcheckoutimportin_personother
- evidencetextoobligatorio
  Lo que aceptó, al pie de la letra, y dónde.
- captured_attextoobligatorio
  Fecha y hora en ISO 8601 con zona horaria.
whatsapp_opt_inobjeto
La prueba de que aceptó recibir WhatsApp: hace falta para enviarle una plantilla si nunca te escribió.
Ver sus 3 datos
- sourceuno de estos valoresobligatorio
  formcheckoutimportin_personother
- evidencetextoobligatorio
  Lo que aceptó, al pie de la letra, y dónde.
- captured_attextoobligatorio
  Fecha y hora en ISO 8601 con zona horaria.
if_existsuno de estos valores
Si ya existe un contacto con ese teléfono: update (por defecto), fill_missing, ignore o error.
updatefill_missingignoreerror
actionslista de objeto o objeto o objeto o objeto o objeto o objeto o objeto o objeto o objeto o objeto o objeto o objeto
Lo que se hace con el contacto después de crearlo o encontrarlo, en orden.
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/contacts" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Idempotency-Key: createContact-A-1043" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+57 300 123 4567","email":"ana@correo.com","first_name":"Ana","last_name":"Gómez","tags":["Lead web"],"fields":{"Ciudad":"Cali"},"broadcasts_subscribed":true,"consent":{"source":"form","evidence":"Marcó «Quiero recibir ofertas» en el formulario de la web","captured_at":"2026-09-26T14:02:00-05:00"},"whatsapp_opt_in":{"source":"form","evidence":"Marcó «Acepto que me escriban por WhatsApp»","captured_at":"2026-09-26T14:02:00-05:00"},"if_exists":"update","actions":[{"type":"run_flow","flow_id":"6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a"}]}'

Responde 201

idtextoobligatorio
Identificador (uuid).
objectsiempre "contact"obligatorio
channeltextoobligatorio
El canal por el que existe este contacto: whatsapp, webchat, messenger o instagram.
first_nametexto o nullobligatorio
last_nametexto o nullobligatorio
full_nametexto o nullobligatorio
phonetexto o nullobligatorio
Teléfono en E.164, con «+».
emailtexto o nullobligatorio
email_verifiedsí/no (booleano)obligatorio
whatsappobjeto o nullobligatorio
Ver sus 3 datos
- wa_idtexto o nullobligatorio
- bsuidtexto o nullobligatorio
- usernametexto o nullobligatorio
profile_pic_urltexto o nullobligatorio
localetexto o nullobligatorio
timezonetexto o nullobligatorio
originuno de estos valores o nullobligatorio
addirect_messagewebchatimportcallphone_appexternal_system
tagslista de objetoobligatorio
Ver sus 2 datos
- idtextoobligatorio
  Identificador (uuid).
- nametextoobligatorio
fieldsobjetoobligatorio
Los campos con valor, cada uno en su tipo: número, booleano, «AAAA-MM-DD», lista…
broadcasts_subscribedsí/no (booleano)obligatorio
broadcasts_opt_outobjeto o nullobligatorio
Ver sus 2 datos
- byuno de estos valoresobligatorio
  contactteamflowapi
- attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_opt_inobjeto o nullobligatorio
Ver sus 3 datos
- statusuno de estos valoresobligatorio
  grantedrevoked
- sourcetextoobligatorio
- captured_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
email_unsubscribedsí/no (booleano)obligatorio
blockedsí/no (booleano)obligatorio
interactions_countnúmero enteroobligatorio
has_writtensí/no (booleano)obligatorio
Si escribió alguna vez. Si no, una plantilla necesita su permiso de WhatsApp.
last_inbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
last_outbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_windowslista de objetoobligatorio
La ventana de 24 horas con cada número de WhatsApp del negocio.
Ver sus 3 datos
- channel_idtextoobligatorio
  Identificador (uuid).
- opensí/no (booleano)obligatorio
- closes_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
actions_resultlista de objeto
Cómo le fue a cada acción, en el mismo orden en que llegaron.
Ver sus 3 datos
- typetextoobligatorio
- oksí/no (booleano)obligatorio
- errorobjeto
  Ver sus 2 datos
  - codetextoobligatorio
  - messagetextoobligatorio

Ver una respuesta de ejemplo

{
  "id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "object": "contact",
  "channel": "whatsapp",
  "first_name": "Ana",
  "last_name": "Gómez",
  "full_name": "Ana Gómez",
  "phone": "+573001234567",
  "email": "ana@correo.com",
  "email_verified": false,
  "whatsapp": {
    "wa_id": "573001234567",
    "bsuid": null,
    "username": null
  },
  "profile_pic_url": null,
  "locale": null,
  "timezone": "America/Bogota",
  "origin": "external_system",
  "tags": [
    {
      "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "name": "Lead web"
    }
  ],
  "fields": {
    "Ciudad": "Cali",
    "Talla": "M",
    "Cumpleaños": "1990-05-14",
    "Aceptó los términos": true
  },
  "broadcasts_subscribed": true,
  "broadcasts_opt_out": null,
  "whatsapp_opt_in": {
    "status": "granted",
    "source": "form",
    "captured_at": "2026-09-26T19:02:00.000Z"
  },
  "email_unsubscribed": false,
  "blocked": false,
  "interactions_count": 12,
  "has_written": true,
  "last_inbound_at": "2026-09-26T14:40:00.000Z",
  "last_outbound_at": "2026-09-26T14:41:10.000Z",
  "whatsapp_windows": [
    {
      "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "open": true,
      "closes_at": "2026-09-27T14:40:00.000Z"
    }
  ],
  "created_at": "2026-09-01T10:00:00.000Z",
  "updated_at": "2026-09-26T14:41:10.000Z",
  "actions_result": [
    {
      "type": "run_flow",
      "ok": true
    }
  ]
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 invalid_phoneEl teléfono no es válido. Escríbelo con el indicativo del país, por ejemplo +57 300 123 4567.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
402 plan_contact_limitLa cuenta llegó a los contactos de su plan. Para agregar más, amplía el plan o suma contactos adicionales.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 already_existsYa existe uno con ese nombre.
409 contact_opted_outEste contacto pidió no recibir mensajes: solo él puede volver a suscribirse escribiéndote.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
422 invalid_field_valueEl valor del campo «…» no es válido.
422 phone_requiredPara crear un contacto hace falta su teléfono.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts

PATCH/contacts/{id}

Cambiar los datos de un contacto

Lo que no envías no se toca. El teléfono de un contacto que ya te escribió por WhatsApp no se cambia (lo pone WhatsApp). Volver a suscribirlo a la publicidad exige la prueba del permiso, y nunca vale si se dio de baja por su cuenta. Un cambio de nombre, teléfono o correo queda en su ficha con el nombre de tu clave.

Permiso contacts:write («Crear y editar contactos») · operationId updateContact · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

first_nametexto o null
last_nametexto o null
phonetexto o null
Solo si el contacto nunca te escribió por WhatsApp (409 contact_readonly_field).
emailtexto o null
timezonetexto o null
Zona horaria IANA.
broadcasts_subscribedsí/no (booleano)
consentobjeto
La prueba del permiso: de dónde viene, qué aceptó el cliente y cuándo.
Ver sus 3 datos
- sourceuno de estos valoresobligatorio
  formcheckoutimportin_personother
- evidencetextoobligatorio
  Lo que aceptó, al pie de la letra, y dónde.
- captured_attextoobligatorio
  Fecha y hora en ISO 8601 con zona horaria.
blockedsí/no (booleano)
fieldsobjeto
Los campos por su clave, cada uno con su valor. null vacía el campo.
tagslista de texto
Etiquetas que se AGREGAN (por nombre o por id). Para quitar una: DELETE /contacts/{id}/tags/{tag}.
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X PATCH "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Ana María","fields":{"Talla":"M"},"tags":["VIP"]}'

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "contact"obligatorio
channeltextoobligatorio
El canal por el que existe este contacto: whatsapp, webchat, messenger o instagram.
first_nametexto o nullobligatorio
last_nametexto o nullobligatorio
full_nametexto o nullobligatorio
phonetexto o nullobligatorio
Teléfono en E.164, con «+».
emailtexto o nullobligatorio
email_verifiedsí/no (booleano)obligatorio
whatsappobjeto o nullobligatorio
Ver sus 3 datos
- wa_idtexto o nullobligatorio
- bsuidtexto o nullobligatorio
- usernametexto o nullobligatorio
profile_pic_urltexto o nullobligatorio
localetexto o nullobligatorio
timezonetexto o nullobligatorio
originuno de estos valores o nullobligatorio
addirect_messagewebchatimportcallphone_appexternal_system
tagslista de objetoobligatorio
Ver sus 2 datos
- idtextoobligatorio
  Identificador (uuid).
- nametextoobligatorio
fieldsobjetoobligatorio
Los campos con valor, cada uno en su tipo: número, booleano, «AAAA-MM-DD», lista…
broadcasts_subscribedsí/no (booleano)obligatorio
broadcasts_opt_outobjeto o nullobligatorio
Ver sus 2 datos
- byuno de estos valoresobligatorio
  contactteamflowapi
- attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_opt_inobjeto o nullobligatorio
Ver sus 3 datos
- statusuno de estos valoresobligatorio
  grantedrevoked
- sourcetextoobligatorio
- captured_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
email_unsubscribedsí/no (booleano)obligatorio
blockedsí/no (booleano)obligatorio
interactions_countnúmero enteroobligatorio
has_writtensí/no (booleano)obligatorio
Si escribió alguna vez. Si no, una plantilla necesita su permiso de WhatsApp.
last_inbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
last_outbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_windowslista de objetoobligatorio
La ventana de 24 horas con cada número de WhatsApp del negocio.
Ver sus 3 datos
- channel_idtextoobligatorio
  Identificador (uuid).
- opensí/no (booleano)obligatorio
- closes_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "object": "contact",
  "channel": "whatsapp",
  "first_name": "Ana",
  "last_name": "Gómez",
  "full_name": "Ana Gómez",
  "phone": "+573001234567",
  "email": "ana@correo.com",
  "email_verified": false,
  "whatsapp": {
    "wa_id": "573001234567",
    "bsuid": null,
    "username": null
  },
  "profile_pic_url": null,
  "locale": null,
  "timezone": "America/Bogota",
  "origin": "external_system",
  "tags": [
    {
      "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "name": "Lead web"
    }
  ],
  "fields": {
    "Ciudad": "Cali",
    "Talla": "M",
    "Cumpleaños": "1990-05-14",
    "Aceptó los términos": true
  },
  "broadcasts_subscribed": true,
  "broadcasts_opt_out": null,
  "whatsapp_opt_in": {
    "status": "granted",
    "source": "form",
    "captured_at": "2026-09-26T19:02:00.000Z"
  },
  "email_unsubscribed": false,
  "blocked": false,
  "interactions_count": 12,
  "has_written": true,
  "last_inbound_at": "2026-09-26T14:40:00.000Z",
  "last_outbound_at": "2026-09-26T14:41:10.000Z",
  "whatsapp_windows": [
    {
      "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "open": true,
      "closes_at": "2026-09-27T14:40:00.000Z"
    }
  ],
  "created_at": "2026-09-01T10:00:00.000Z",
  "updated_at": "2026-09-26T14:41:10.000Z"
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 invalid_phoneEl teléfono no es válido. Escríbelo con el indicativo del país, por ejemplo +57 300 123 4567.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 contact_opted_outEste contacto pidió no recibir mensajes: solo él puede volver a suscribirse escribiéndote.
409 contact_readonly_fieldEste contacto ya te escribió por WhatsApp: su teléfono lo pone WhatsApp y no se cambia por la API.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
422 invalid_field_valueEl valor del campo «…» no es válido.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}

DELETE/contacts/{id}

Enviar un contacto a la papelera (se puede restaurar 30 días desde el panel)

Desaparece de la bandeja, de Contactos, de los flujos y de la API, y sus citas por venir se cancelan (se libera la hora). Pasados 30 días se borra de verdad. Hasta 500 al día por clave. En la prueba gratis no se borran contactos por la API.

Permiso contacts:delete («Borrar contactos») · operationId deleteContact · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Ejemplo

curl -X DELETE "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "deleted_contact"obligatorio
phonetexto o nullobligatorio
Teléfono en E.164, con «+».
emailtexto o nullobligatorio
deleted_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
deleted_byobjetoobligatorio
Quién lo hizo.
Ver sus 3 datos
- typeuno de estos valoresobligatorio
  contactaiflowruleteam_memberapi_keysystem
- idtexto o nullobligatorio
- nametexto o nullobligatorio

Ver una respuesta de ejemplo

{
  "id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "object": "deleted_contact",
  "phone": "+573001234567",
  "email": "ana@correo.com",
  "deleted_at": "2026-09-27T15:00:00.000Z",
  "deleted_by": {
    "type": "api_key",
    "id": "0f1e2d3c-4b5a-4968-8776-65a4b3c2d1e0",
    "name": "Tienda Shopify"
  }
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
403 not_available_in_trialEsto no está disponible en la prueba gratis: se habilita al elegir un plan.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}

GET/contacts/deleted

Los contactos que entraron a la papelera en los últimos 30 días

Para sincronizar los borrados sin recibir avisos. ?since= incluye el instante que pasas (>=).

Permiso contacts:read («Ver contactos») · operationId listDeletedContacts

Parámetros

limitnúmero entero · en la dirección
De 1 a 100. Por defecto, 25.
cursortexto · en la dirección
El next_cursor de la página anterior.
sincetexto · en la dirección
Fecha y hora en ISO 8601 con zona horaria.

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/contacts/deleted" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

idtextoobligatorio
Identificador (uuid).
objectsiempre "deleted_contact"obligatorio
phonetexto o nullobligatorio
Teléfono en E.164, con «+».
emailtexto o nullobligatorio
deleted_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
deleted_byobjetoobligatorio
Quién lo hizo.
Ver sus 3 datos
- typeuno de estos valoresobligatorio
  contactaiflowruleteam_memberapi_keysystem
- idtexto o nullobligatorio
- nametexto o nullobligatorio

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
      "object": "deleted_contact",
      "phone": "+573001234567",
      "email": null,
      "deleted_at": "2026-09-27T15:00:00.000Z",
      "deleted_by": {
        "type": "team_member",
        "id": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a",
        "name": "Laura Pérez"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

400 date_without_timezoneLa fecha «…» tiene que llevar zona horaria, por ejemplo 2026-09-27T10:00:00-05:00.
400 invalid_cursorEl cursor no es válido o cambiaron los filtros. Empieza la lista de nuevo.
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/deleted

POST/contacts/{id}/whatsapp-consent

Guardar la prueba de que el contacto aceptó (o retiró) recibir WhatsApp

Para enviarle una plantilla a alguien que nunca te escribió hace falta esta constancia: la política de WhatsApp Business exige el permiso previo y, sin constancia, tu negocio queda sin pruebas ante un reporte. Queda guardada con tu clave y no se borra.

Permiso contacts:write («Crear y editar contactos») · operationId setWhatsappConsent · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

statusuno de estos valoresobligatorio
grantedrevoked
sourceuno de estos valoresobligatorio
formcheckoutimportin_personother
evidencetexto
Obligatoria al dar el permiso: lo que aceptó, al pie de la letra, y dónde.
captured_attexto
Obligatoria al dar el permiso: cuándo lo aceptó.
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/whatsapp-consent" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Idempotency-Key: setWhatsappConsent-A-1043" \
  -H "Content-Type: application/json" \
  -d '{"status":"granted","source":"checkout","evidence":"Marcó «Quiero recibir el estado de mi pedido por WhatsApp» en el pago","captured_at":"2026-09-26T14:02:00-05:00"}'

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "contact"obligatorio
channeltextoobligatorio
El canal por el que existe este contacto: whatsapp, webchat, messenger o instagram.
first_nametexto o nullobligatorio
last_nametexto o nullobligatorio
full_nametexto o nullobligatorio
phonetexto o nullobligatorio
Teléfono en E.164, con «+».
emailtexto o nullobligatorio
email_verifiedsí/no (booleano)obligatorio
whatsappobjeto o nullobligatorio
Ver sus 3 datos
- wa_idtexto o nullobligatorio
- bsuidtexto o nullobligatorio
- usernametexto o nullobligatorio
profile_pic_urltexto o nullobligatorio
localetexto o nullobligatorio
timezonetexto o nullobligatorio
originuno de estos valores o nullobligatorio
addirect_messagewebchatimportcallphone_appexternal_system
tagslista de objetoobligatorio
Ver sus 2 datos
- idtextoobligatorio
  Identificador (uuid).
- nametextoobligatorio
fieldsobjetoobligatorio
Los campos con valor, cada uno en su tipo: número, booleano, «AAAA-MM-DD», lista…
broadcasts_subscribedsí/no (booleano)obligatorio
broadcasts_opt_outobjeto o nullobligatorio
Ver sus 2 datos
- byuno de estos valoresobligatorio
  contactteamflowapi
- attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_opt_inobjeto o nullobligatorio
Ver sus 3 datos
- statusuno de estos valoresobligatorio
  grantedrevoked
- sourcetextoobligatorio
- captured_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
email_unsubscribedsí/no (booleano)obligatorio
blockedsí/no (booleano)obligatorio
interactions_countnúmero enteroobligatorio
has_writtensí/no (booleano)obligatorio
Si escribió alguna vez. Si no, una plantilla necesita su permiso de WhatsApp.
last_inbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
last_outbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_windowslista de objetoobligatorio
La ventana de 24 horas con cada número de WhatsApp del negocio.
Ver sus 3 datos
- channel_idtextoobligatorio
  Identificador (uuid).
- opensí/no (booleano)obligatorio
- closes_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "object": "contact",
  "channel": "whatsapp",
  "first_name": "Ana",
  "last_name": "Gómez",
  "full_name": "Ana Gómez",
  "phone": "+573001234567",
  "email": "ana@correo.com",
  "email_verified": false,
  "whatsapp": {
    "wa_id": "573001234567",
    "bsuid": null,
    "username": null
  },
  "profile_pic_url": null,
  "locale": null,
  "timezone": "America/Bogota",
  "origin": "external_system",
  "tags": [
    {
      "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "name": "Lead web"
    }
  ],
  "fields": {
    "Ciudad": "Cali",
    "Talla": "M",
    "Cumpleaños": "1990-05-14",
    "Aceptó los términos": true
  },
  "broadcasts_subscribed": true,
  "broadcasts_opt_out": null,
  "whatsapp_opt_in": {
    "status": "granted",
    "source": "form",
    "captured_at": "2026-09-26T19:02:00.000Z"
  },
  "email_unsubscribed": false,
  "blocked": false,
  "interactions_count": 12,
  "has_written": true,
  "last_inbound_at": "2026-09-26T14:40:00.000Z",
  "last_outbound_at": "2026-09-26T14:41:10.000Z",
  "whatsapp_windows": [
    {
      "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "open": true,
      "closes_at": "2026-09-27T14:40:00.000Z"
    }
  ],
  "created_at": "2026-09-01T10:00:00.000Z",
  "updated_at": "2026-09-26T14:41:10.000Z"
}

Errores posibles

400 date_without_timezoneLa fecha «…» tiene que llevar zona horaria, por ejemplo 2026-09-27T10:00:00-05:00.
400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}/whatsapp-consent

GET/contacts/{id}/tags

Las etiquetas de un contacto

Permiso contacts:read («Ver contactos») · operationId listContactTags

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/tags" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

idtextoobligatorio
Identificador (uuid).
objectsiempre "tag"obligatorio
nametextoobligatorio
colortexto o nullobligatorio
foldertexto o nullobligatorio
contacts_countnúmero enteroobligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "object": "tag",
      "name": "Lead web",
      "color": "#0f766e",
      "folder": null,
      "contacts_count": 214,
      "created_at": "2026-05-10T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}/tags

POST/contacts/{id}/tags

Agregar etiquetas a un contacto, por nombre o por id

La que ya tenía no avisa. Sin create_missing, si alguna no existe no se pone ninguna (404 con la etiqueta en error.field).

Permiso contacts:write («Crear y editar contactos») · operationId addContactTags · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

tagslista de textoobligatorio
create_missingsí/no (booleano)
Crea las que no existan (por nombre).
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/tags" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Idempotency-Key: addContactTags-A-1043" \
  -H "Content-Type: application/json" \
  -d '{"tags":["VIP","3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d"],"create_missing":false}'

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "contact"obligatorio
channeltextoobligatorio
El canal por el que existe este contacto: whatsapp, webchat, messenger o instagram.
first_nametexto o nullobligatorio
last_nametexto o nullobligatorio
full_nametexto o nullobligatorio
phonetexto o nullobligatorio
Teléfono en E.164, con «+».
emailtexto o nullobligatorio
email_verifiedsí/no (booleano)obligatorio
whatsappobjeto o nullobligatorio
Ver sus 3 datos
- wa_idtexto o nullobligatorio
- bsuidtexto o nullobligatorio
- usernametexto o nullobligatorio
profile_pic_urltexto o nullobligatorio
localetexto o nullobligatorio
timezonetexto o nullobligatorio
originuno de estos valores o nullobligatorio
addirect_messagewebchatimportcallphone_appexternal_system
tagslista de objetoobligatorio
Ver sus 2 datos
- idtextoobligatorio
  Identificador (uuid).
- nametextoobligatorio
fieldsobjetoobligatorio
Los campos con valor, cada uno en su tipo: número, booleano, «AAAA-MM-DD», lista…
broadcasts_subscribedsí/no (booleano)obligatorio
broadcasts_opt_outobjeto o nullobligatorio
Ver sus 2 datos
- byuno de estos valoresobligatorio
  contactteamflowapi
- attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_opt_inobjeto o nullobligatorio
Ver sus 3 datos
- statusuno de estos valoresobligatorio
  grantedrevoked
- sourcetextoobligatorio
- captured_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
email_unsubscribedsí/no (booleano)obligatorio
blockedsí/no (booleano)obligatorio
interactions_countnúmero enteroobligatorio
has_writtensí/no (booleano)obligatorio
Si escribió alguna vez. Si no, una plantilla necesita su permiso de WhatsApp.
last_inbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
last_outbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_windowslista de objetoobligatorio
La ventana de 24 horas con cada número de WhatsApp del negocio.
Ver sus 3 datos
- channel_idtextoobligatorio
  Identificador (uuid).
- opensí/no (booleano)obligatorio
- closes_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "object": "contact",
  "channel": "whatsapp",
  "first_name": "Ana",
  "last_name": "Gómez",
  "full_name": "Ana Gómez",
  "phone": "+573001234567",
  "email": "ana@correo.com",
  "email_verified": false,
  "whatsapp": {
    "wa_id": "573001234567",
    "bsuid": null,
    "username": null
  },
  "profile_pic_url": null,
  "locale": null,
  "timezone": "America/Bogota",
  "origin": "external_system",
  "tags": [
    {
      "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "name": "Lead web"
    }
  ],
  "fields": {
    "Ciudad": "Cali",
    "Talla": "M",
    "Cumpleaños": "1990-05-14",
    "Aceptó los términos": true
  },
  "broadcasts_subscribed": true,
  "broadcasts_opt_out": null,
  "whatsapp_opt_in": {
    "status": "granted",
    "source": "form",
    "captured_at": "2026-09-26T19:02:00.000Z"
  },
  "email_unsubscribed": false,
  "blocked": false,
  "interactions_count": 12,
  "has_written": true,
  "last_inbound_at": "2026-09-26T14:40:00.000Z",
  "last_outbound_at": "2026-09-26T14:41:10.000Z",
  "whatsapp_windows": [
    {
      "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "open": true,
      "closes_at": "2026-09-27T14:40:00.000Z"
    }
  ],
  "created_at": "2026-09-01T10:00:00.000Z",
  "updated_at": "2026-09-26T14:41:10.000Z"
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}/tags

PUT/contacts/{id}/tags/{tag}

Agregar una etiqueta a un contacto (si ya la tiene, no pasa nada)

{tag} es el id de la etiqueta o su nombre (codificado en la dirección).

Permiso contacts:write («Crear y editar contactos») · operationId addContactTag · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
tagtexto · en la rutaobligatorio
La etiqueta, por su id o por su nombre.
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Ejemplo

curl -X PUT "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/tags/VIP" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "contact"obligatorio
channeltextoobligatorio
El canal por el que existe este contacto: whatsapp, webchat, messenger o instagram.
first_nametexto o nullobligatorio
last_nametexto o nullobligatorio
full_nametexto o nullobligatorio
phonetexto o nullobligatorio
Teléfono en E.164, con «+».
emailtexto o nullobligatorio
email_verifiedsí/no (booleano)obligatorio
whatsappobjeto o nullobligatorio
Ver sus 3 datos
- wa_idtexto o nullobligatorio
- bsuidtexto o nullobligatorio
- usernametexto o nullobligatorio
profile_pic_urltexto o nullobligatorio
localetexto o nullobligatorio
timezonetexto o nullobligatorio
originuno de estos valores o nullobligatorio
addirect_messagewebchatimportcallphone_appexternal_system
tagslista de objetoobligatorio
Ver sus 2 datos
- idtextoobligatorio
  Identificador (uuid).
- nametextoobligatorio
fieldsobjetoobligatorio
Los campos con valor, cada uno en su tipo: número, booleano, «AAAA-MM-DD», lista…
broadcasts_subscribedsí/no (booleano)obligatorio
broadcasts_opt_outobjeto o nullobligatorio
Ver sus 2 datos
- byuno de estos valoresobligatorio
  contactteamflowapi
- attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_opt_inobjeto o nullobligatorio
Ver sus 3 datos
- statusuno de estos valoresobligatorio
  grantedrevoked
- sourcetextoobligatorio
- captured_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
email_unsubscribedsí/no (booleano)obligatorio
blockedsí/no (booleano)obligatorio
interactions_countnúmero enteroobligatorio
has_writtensí/no (booleano)obligatorio
Si escribió alguna vez. Si no, una plantilla necesita su permiso de WhatsApp.
last_inbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
last_outbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_windowslista de objetoobligatorio
La ventana de 24 horas con cada número de WhatsApp del negocio.
Ver sus 3 datos
- channel_idtextoobligatorio
  Identificador (uuid).
- opensí/no (booleano)obligatorio
- closes_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "object": "contact",
  "channel": "whatsapp",
  "first_name": "Ana",
  "last_name": "Gómez",
  "full_name": "Ana Gómez",
  "phone": "+573001234567",
  "email": "ana@correo.com",
  "email_verified": false,
  "whatsapp": {
    "wa_id": "573001234567",
    "bsuid": null,
    "username": null
  },
  "profile_pic_url": null,
  "locale": null,
  "timezone": "America/Bogota",
  "origin": "external_system",
  "tags": [
    {
      "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "name": "Lead web"
    }
  ],
  "fields": {
    "Ciudad": "Cali",
    "Talla": "M",
    "Cumpleaños": "1990-05-14",
    "Aceptó los términos": true
  },
  "broadcasts_subscribed": true,
  "broadcasts_opt_out": null,
  "whatsapp_opt_in": {
    "status": "granted",
    "source": "form",
    "captured_at": "2026-09-26T19:02:00.000Z"
  },
  "email_unsubscribed": false,
  "blocked": false,
  "interactions_count": 12,
  "has_written": true,
  "last_inbound_at": "2026-09-26T14:40:00.000Z",
  "last_outbound_at": "2026-09-26T14:41:10.000Z",
  "whatsapp_windows": [
    {
      "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "open": true,
      "closes_at": "2026-09-27T14:40:00.000Z"
    }
  ],
  "created_at": "2026-09-01T10:00:00.000Z",
  "updated_at": "2026-09-26T14:41:10.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}/tags/{tag}

DELETE/contacts/{id}/tags/{tag}

Quitar una etiqueta de un contacto, por id o por nombre

Si no la tenía, responde igual con el contacto.

Permiso contacts:write («Crear y editar contactos») · operationId removeContactTag · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
tagtexto · en la rutaobligatorio
La etiqueta, por su id o por su nombre.
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Ejemplo

curl -X DELETE "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/tags/VIP" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "contact"obligatorio
channeltextoobligatorio
El canal por el que existe este contacto: whatsapp, webchat, messenger o instagram.
first_nametexto o nullobligatorio
last_nametexto o nullobligatorio
full_nametexto o nullobligatorio
phonetexto o nullobligatorio
Teléfono en E.164, con «+».
emailtexto o nullobligatorio
email_verifiedsí/no (booleano)obligatorio
whatsappobjeto o nullobligatorio
Ver sus 3 datos
- wa_idtexto o nullobligatorio
- bsuidtexto o nullobligatorio
- usernametexto o nullobligatorio
profile_pic_urltexto o nullobligatorio
localetexto o nullobligatorio
timezonetexto o nullobligatorio
originuno de estos valores o nullobligatorio
addirect_messagewebchatimportcallphone_appexternal_system
tagslista de objetoobligatorio
Ver sus 2 datos
- idtextoobligatorio
  Identificador (uuid).
- nametextoobligatorio
fieldsobjetoobligatorio
Los campos con valor, cada uno en su tipo: número, booleano, «AAAA-MM-DD», lista…
broadcasts_subscribedsí/no (booleano)obligatorio
broadcasts_opt_outobjeto o nullobligatorio
Ver sus 2 datos
- byuno de estos valoresobligatorio
  contactteamflowapi
- attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_opt_inobjeto o nullobligatorio
Ver sus 3 datos
- statusuno de estos valoresobligatorio
  grantedrevoked
- sourcetextoobligatorio
- captured_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
email_unsubscribedsí/no (booleano)obligatorio
blockedsí/no (booleano)obligatorio
interactions_countnúmero enteroobligatorio
has_writtensí/no (booleano)obligatorio
Si escribió alguna vez. Si no, una plantilla necesita su permiso de WhatsApp.
last_inbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
last_outbound_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
whatsapp_windowslista de objetoobligatorio
La ventana de 24 horas con cada número de WhatsApp del negocio.
Ver sus 3 datos
- channel_idtextoobligatorio
  Identificador (uuid).
- opensí/no (booleano)obligatorio
- closes_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "object": "contact",
  "channel": "whatsapp",
  "first_name": "Ana",
  "last_name": "Gómez",
  "full_name": "Ana Gómez",
  "phone": "+573001234567",
  "email": "ana@correo.com",
  "email_verified": false,
  "whatsapp": {
    "wa_id": "573001234567",
    "bsuid": null,
    "username": null
  },
  "profile_pic_url": null,
  "locale": null,
  "timezone": "America/Bogota",
  "origin": "external_system",
  "tags": [
    {
      "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "name": "Lead web"
    }
  ],
  "fields": {
    "Ciudad": "Cali",
    "Talla": "M",
    "Cumpleaños": "1990-05-14",
    "Aceptó los términos": true
  },
  "broadcasts_subscribed": true,
  "broadcasts_opt_out": null,
  "whatsapp_opt_in": {
    "status": "granted",
    "source": "form",
    "captured_at": "2026-09-26T19:02:00.000Z"
  },
  "email_unsubscribed": false,
  "blocked": false,
  "interactions_count": 12,
  "has_written": true,
  "last_inbound_at": "2026-09-26T14:40:00.000Z",
  "last_outbound_at": "2026-09-26T14:41:10.000Z",
  "whatsapp_windows": [
    {
      "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "open": true,
      "closes_at": "2026-09-27T14:40:00.000Z"
    }
  ],
  "created_at": "2026-09-01T10:00:00.000Z",
  "updated_at": "2026-09-26T14:41:10.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}/tags/{tag}

GET/contacts/{id}/fields

Todos los campos de la cuenta con el valor de este contacto (o null)

Permiso contacts:read («Ver contactos») · operationId listContactFields

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/fields" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

keytextoobligatorio
objectsiempre "field_value"obligatorio
nametextoobligatorio
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
valuecualquier valorobligatorio

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "key": "Ciudad",
      "object": "field_value",
      "name": "Ciudad",
      "type": "single_choice",
      "value": "Cali"
    },
    {
      "key": "Talla",
      "object": "field_value",
      "name": "Talla",
      "type": "single_choice",
      "value": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}/fields

GET/contacts/{id}/fields/{key}

Un campo de un contacto, por clave o por id

Permiso contacts:read («Ver contactos») · operationId getContactField

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
keytexto · en la rutaobligatorio
El campo, por su clave (ciudad) o por su id.

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/fields/Ciudad%20de%20env%C3%ADo" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

keytextoobligatorio
objectsiempre "field_value"obligatorio
nametextoobligatorio
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
valuecualquier valorobligatorio

Ver una respuesta de ejemplo

{
  "key": "Ciudad",
  "object": "field_value",
  "name": "Ciudad",
  "type": "single_choice",
  "value": "Cali"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}/fields/{key}

PATCH/contacts/{id}/fields

Cambiar varios campos de un contacto a la vez (null vacía el campo)

Cada valor se valida por el tipo del campo. Poner el mismo valor que ya tenía no cambia nada ni avisa.

Permiso contacts:write («Crear y editar contactos») · operationId updateContactFields · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

Sin datos.

Ejemplo

curl -X PATCH "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/fields" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"Ciudad":"Cali","Talla":null}'

Responde 200: una lista; cada elemento de data trae

keytextoobligatorio
objectsiempre "field_value"obligatorio
nametextoobligatorio
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
valuecualquier valorobligatorio

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "key": "Ciudad",
      "object": "field_value",
      "name": "Ciudad",
      "type": "single_choice",
      "value": "Cali"
    },
    {
      "key": "Talla",
      "object": "field_value",
      "name": "Talla",
      "type": "single_choice",
      "value": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
422 invalid_field_valueEl valor del campo «…» no es válido.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}/fields

PUT/contacts/{id}/fields/{key}

Cambiar un campo de un contacto

Permiso contacts:write («Crear y editar contactos») · operationId setContactField · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
keytexto · en la rutaobligatorio
El campo, por su clave (ciudad) o por su id.
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

valuetexto o número o sí/no (booleano) o lista de texto o nuloobligatorio
El valor en su tipo: texto, número, true/false, lista de opciones, o null para vaciarlo.
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X PUT "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/fields/Ciudad%20de%20env%C3%ADo" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"value":"Cali"}'

Responde 200

keytextoobligatorio
objectsiempre "field_value"obligatorio
nametextoobligatorio
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
valuecualquier valorobligatorio

Ver una respuesta de ejemplo

{
  "key": "Ciudad",
  "object": "field_value",
  "name": "Ciudad",
  "type": "single_choice",
  "value": "Cali"
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
422 invalid_field_valueEl valor del campo «…» no es válido.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}/fields/{key}

DELETE/contacts/{id}/fields/{key}

Vaciar un campo de un contacto

Permiso contacts:write («Crear y editar contactos») · operationId clearContactField · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
keytexto · en la rutaobligatorio
El campo, por su clave (ciudad) o por su id.
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Ejemplo

curl -X DELETE "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/fields/Ciudad%20de%20env%C3%ADo" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

keytextoobligatorio
objectsiempre "field_value"obligatorio
nametextoobligatorio
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
valuecualquier valorobligatorio

Ver una respuesta de ejemplo

{
  "key": "Ciudad",
  "object": "field_value",
  "name": "Ciudad",
  "type": "single_choice",
  "value": null
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}/fields/{key}

Etiquetas

GET/tags

Por orden alfabético. ?name= busca sin distinguir mayúsculas.

Permiso contacts:read («Ver contactos») · operationId listTags

Parámetros

limitnúmero entero · en la dirección
De 1 a 100. Por defecto, 25.
cursortexto · en la dirección
El next_cursor de la página anterior.
nametexto · en la dirección

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/tags" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

idtextoobligatorio
Identificador (uuid).
objectsiempre "tag"obligatorio
nametextoobligatorio
colortexto o nullobligatorio
foldertexto o nullobligatorio
contacts_countnúmero enteroobligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "object": "tag",
      "name": "VIP",
      "color": "#b45309",
      "folder": "Clientes",
      "contacts_count": 58,
      "created_at": "2026-05-10T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

400 invalid_cursorEl cursor no es válido o cambiaron los filtros. Empieza la lista de nuevo.
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/tags

POST/tags

Crear una etiqueta

Si ya existe una con ese nombre (sin distinguir mayúsculas), responde 409 con su id en details.existing_id.

Permiso contacts:write («Crear y editar contactos») · operationId createTag · acepta Idempotency-Key

Parámetros

Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

nametextoobligatorio
De 1 a 40 letras. Único en la cuenta.
colortexto o null
foldertexto o null
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/tags" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Idempotency-Key: createTag-A-1043" \
  -H "Content-Type: application/json" \
  -d '{"name":"VIP","color":"#b45309","folder":"Clientes"}'

Responde 201

idtextoobligatorio
Identificador (uuid).
objectsiempre "tag"obligatorio
nametextoobligatorio
colortexto o nullobligatorio
foldertexto o nullobligatorio
contacts_countnúmero enteroobligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "object": "tag",
  "name": "VIP",
  "color": "#b45309",
  "folder": "Clientes",
  "contacts_count": 0,
  "created_at": "2026-05-10T12:00:00.000Z"
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
409 already_existsYa existe uno con ese nombre.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/tags

GET/tags/{id}

Una etiqueta

Permiso contacts:read («Ver contactos») · operationId getTag

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/tags/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "tag"obligatorio
nametextoobligatorio
colortexto o nullobligatorio
foldertexto o nullobligatorio
contacts_countnúmero enteroobligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "object": "tag",
  "name": "VIP",
  "color": "#b45309",
  "folder": "Clientes",
  "contacts_count": 58,
  "created_at": "2026-05-10T12:00:00.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/tags/{id}

PATCH/tags/{id}

Cambiar el nombre, el color o la carpeta de una etiqueta

Lo que no envías no se toca; null quita el color o la carpeta.

Permiso contacts:write («Crear y editar contactos») · operationId updateTag · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

nametexto
De 1 a 40 letras. Único en la cuenta.
colortexto o null
foldertexto o null
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X PATCH "https://panel.adsmartbot.com/api/v1/tags/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cliente VIP"}'

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "tag"obligatorio
nametextoobligatorio
colortexto o nullobligatorio
foldertexto o nullobligatorio
contacts_countnúmero enteroobligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "object": "tag",
  "name": "Cliente VIP",
  "color": "#b45309",
  "folder": "Clientes",
  "contacts_count": 58,
  "created_at": "2026-05-10T12:00:00.000Z"
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 already_existsYa existe uno con ese nombre.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/tags/{id}

DELETE/tags/{id}

Borrar una etiqueta y quitársela a todos

Como en el panel, no avisa «Se le quita una etiqueta» por cada contacto. Responde con la etiqueta como estaba.

Permiso contacts:write («Crear y editar contactos») · operationId deleteTag · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Ejemplo

curl -X DELETE "https://panel.adsmartbot.com/api/v1/tags/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "tag"obligatorio
nametextoobligatorio
colortexto o nullobligatorio
foldertexto o nullobligatorio
contacts_countnúmero enteroobligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "object": "tag",
  "name": "VIP",
  "color": "#b45309",
  "folder": "Clientes",
  "contacts_count": 58,
  "created_at": "2026-05-10T12:00:00.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/tags/{id}

Campos

GET/fields

Todos los campos (?scope=contact|global, ?name=)

Los campos iguales para todos marcados «Privado» en el panel no salen.

Permiso contacts:read («Ver contactos») · operationId listFields

Parámetros

limitnúmero entero · en la dirección
De 1 a 100. Por defecto, 25.
cursortexto · en la dirección
El next_cursor de la página anterior.
scopeuno de estos valores · en la dirección
nametexto · en la dirección
Busca por nombre o clave, sin distinguir mayúsculas.

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/fields" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

idtextoobligatorio
Identificador (uuid).
objectsiempre "field"obligatorio
keytextoobligatorio
La clave: el nombre tal cual, lo que va entre llaves, {{Ciudad}}.
nametextoobligatorio
scopeuno de estos valoresobligatorio
contactglobal
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
optionslista de textoobligatorio
descriptiontexto o nullobligatorio
foldertexto o nullobligatorio
show_in_inboxsí/no (booleano)obligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "id": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a",
      "object": "field",
      "key": "Ciudad",
      "name": "Ciudad",
      "scope": "contact",
      "type": "single_choice",
      "options": [
        "Bogotá",
        "Cali",
        "Medellín"
      ],
      "description": "Dónde recibe los pedidos.",
      "folder": null,
      "show_in_inbox": true,
      "created_at": "2026-04-02T10:00:00.000Z",
      "updated_at": "2026-09-20T16:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

400 invalid_cursorEl cursor no es válido o cambiaron los filtros. Empieza la lista de nuevo.
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/fields

POST/fields

Crear un campo (la clave es el nombre tal cual)

Acepta los 8 tipos. La clave es el nombre tal cual, con sus mayúsculas, tildes y espacios, y es lo que va entre llaves ({{Ciudad de envío}}); «Ciudad» y «ciudad» son dos campos distintos. En una dirección va codificada: /fields/Ciudad%20de%20env%C3%ADo. El nombre no puede llevar llaves { } ni saltos de línea. Un campo igual para todos puede nacer con su valor (value).

Permiso contacts:write («Crear y editar contactos») · operationId createField · acepta Idempotency-Key

Parámetros

Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

nametextoobligatorio
keytexto
Si la envías, tiene que ser igual a name: la clave de un campo es su nombre tal cual.
scopeuno de estos valores
Por defecto, contact.
contactglobal
typeuno de estos valores
Por defecto, text.
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
optionslista de texto
Las opciones de single_choice y multiple_choice.
descriptiontexto o null
foldertexto o null
show_in_inboxsí/no (booleano)
valuetexto o número o sí/no (booleano) o lista de texto o nulo
Solo en un campo igual para todos: su valor inicial.
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/fields" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Idempotency-Key: createField-A-1043" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ciudad","type":"single_choice","options":["Bogotá","Cali","Medellín"],"description":"Dónde recibe los pedidos."}'

Responde 201

idtextoobligatorio
Identificador (uuid).
objectsiempre "field"obligatorio
keytextoobligatorio
La clave: el nombre tal cual, lo que va entre llaves, {{Ciudad}}.
nametextoobligatorio
scopeuno de estos valoresobligatorio
contactglobal
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
optionslista de textoobligatorio
descriptiontexto o nullobligatorio
foldertexto o nullobligatorio
show_in_inboxsí/no (booleano)obligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a",
  "object": "field",
  "key": "Ciudad",
  "name": "Ciudad",
  "scope": "contact",
  "type": "single_choice",
  "options": [
    "Bogotá",
    "Cali",
    "Medellín"
  ],
  "description": "Dónde recibe los pedidos.",
  "folder": null,
  "show_in_inbox": true,
  "created_at": "2026-04-02T10:00:00.000Z",
  "updated_at": "2026-09-20T16:30:00.000Z"
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
409 already_existsYa existe uno con ese nombre.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
422 invalid_field_valueEl valor del campo «…» no es válido.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/fields

GET/fields/{field}

Un campo, por id o por clave (codificada: /fields/Ciudad%20de%20env%C3%ADo)

Permiso contacts:read («Ver contactos») · operationId getField

Parámetros

fieldtexto · en la rutaobligatorio
El campo, por su clave (ciudad) o por su id.

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/fields/Ciudad%20de%20env%C3%ADo" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "field"obligatorio
keytextoobligatorio
La clave: el nombre tal cual, lo que va entre llaves, {{Ciudad}}.
nametextoobligatorio
scopeuno de estos valoresobligatorio
contactglobal
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
optionslista de textoobligatorio
descriptiontexto o nullobligatorio
foldertexto o nullobligatorio
show_in_inboxsí/no (booleano)obligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a",
  "object": "field",
  "key": "Ciudad",
  "name": "Ciudad",
  "scope": "contact",
  "type": "single_choice",
  "options": [
    "Bogotá",
    "Cali",
    "Medellín"
  ],
  "description": "Dónde recibe los pedidos.",
  "folder": null,
  "show_in_inbox": true,
  "created_at": "2026-04-02T10:00:00.000Z",
  "updated_at": "2026-09-20T16:30:00.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/fields/{field}

PATCH/fields/{field}

Cambiar el nombre, la descripción, las opciones, la carpeta o si se ve en la bandeja

Cambiar name cambia también key y la reescribe en tus flujos, plantillas e instrucciones, como en el panel. Quien te envíe datos con la clave vieja tiene que usar la nueva.

Permiso contacts:write («Crear y editar contactos») · operationId updateField · acepta Idempotency-Key

Parámetros

fieldtexto · en la rutaobligatorio
El campo, por su clave (ciudad) o por su id.
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

nametexto
descriptiontexto o null
optionslista de texto
Las opciones de single_choice y multiple_choice.
foldertexto o null
show_in_inboxsí/no (booleano)
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X PATCH "https://panel.adsmartbot.com/api/v1/fields/Ciudad%20de%20env%C3%ADo" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"options":["Bogotá","Cali","Medellín","Pereira"]}'

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "field"obligatorio
keytextoobligatorio
La clave: el nombre tal cual, lo que va entre llaves, {{Ciudad}}.
nametextoobligatorio
scopeuno de estos valoresobligatorio
contactglobal
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
optionslista de textoobligatorio
descriptiontexto o nullobligatorio
foldertexto o nullobligatorio
show_in_inboxsí/no (booleano)obligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a",
  "object": "field",
  "key": "Ciudad",
  "name": "Ciudad",
  "scope": "contact",
  "type": "single_choice",
  "options": [
    "Bogotá",
    "Cali",
    "Medellín",
    "Pereira"
  ],
  "description": "Dónde recibe los pedidos.",
  "folder": null,
  "show_in_inbox": true,
  "created_at": "2026-04-02T10:00:00.000Z",
  "updated_at": "2026-09-20T16:30:00.000Z"
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/fields/{field}

Iguales para todos

GET/global-fields

Los campos iguales para todos, con su valor (los privados no salen)

Un campo igual para todos es uno solo para toda la cuenta: el menú del día, el precio del domicilio. Los marcados «Privado» (claves de otros sistemas) no salen con ningún permiso.

Permiso contacts:read («Ver contactos») · operationId listGlobalFields

Parámetros

limitnúmero entero · en la dirección
De 1 a 100. Por defecto, 25.
cursortexto · en la dirección
El next_cursor de la página anterior.

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/global-fields" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

keytextoobligatorio
objectsiempre "field_value"obligatorio
nametextoobligatorio
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
valuecualquier valorobligatorio
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "key": "Menú del día",
      "object": "field_value",
      "name": "Menú del día",
      "type": "text",
      "value": "Bandeja paisa",
      "updated_at": "2026-09-27T11:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

400 invalid_cursorEl cursor no es válido o cambiaron los filtros. Empieza la lista de nuevo.
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/global-fields

GET/global-fields/{key}

Un campo igual para todos

Permiso contacts:read («Ver contactos») · operationId getGlobalField

Parámetros

keytexto · en la rutaobligatorio
El campo, por su clave (ciudad) o por su id.

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/global-fields/Men%C3%BA%20del%20d%C3%ADa" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

keytextoobligatorio
objectsiempre "field_value"obligatorio
nametextoobligatorio
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
valuecualquier valorobligatorio
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "key": "Menú del día",
  "object": "field_value",
  "name": "Menú del día",
  "type": "text",
  "value": "Bandeja paisa",
  "updated_at": "2026-09-27T11:00:00.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/global-fields/{key}

PUT/global-fields/{key}

Cambiar el valor de un campo igual para todos (lo leen todos tus clientes y la IA a la vez)

Se valida por el tipo del campo. Lo que escribe la API la IA lo lee como un dato del negocio, nunca como una instrucción, y con 2.000 caracteres como mucho.

Permiso global_fields:write («Cambiar los datos iguales para todos») · operationId setGlobalField · acepta Idempotency-Key

Parámetros

keytexto · en la rutaobligatorio
El campo, por su clave (ciudad) o por su id.
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

valuetexto o número o sí/no (booleano) o lista de texto o nuloobligatorio
El valor en su tipo: texto, número, true/false, lista de opciones, o null para vaciarlo.
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X PUT "https://panel.adsmartbot.com/api/v1/global-fields/Men%C3%BA%20del%20d%C3%ADa" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"value":"Bandeja paisa"}'

Responde 200

keytextoobligatorio
objectsiempre "field_value"obligatorio
nametextoobligatorio
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
valuecualquier valorobligatorio
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "key": "Menú del día",
  "object": "field_value",
  "name": "Menú del día",
  "type": "text",
  "value": "Bandeja paisa",
  "updated_at": "2026-09-27T11:00:00.000Z"
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
422 invalid_field_valueEl valor del campo «…» no es válido.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/global-fields/{key}

DELETE/global-fields/{key}

Vaciar un campo igual para todos

Permiso global_fields:write («Cambiar los datos iguales para todos») · operationId clearGlobalField · acepta Idempotency-Key

Parámetros

keytexto · en la rutaobligatorio
El campo, por su clave (ciudad) o por su id.
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Ejemplo

curl -X DELETE "https://panel.adsmartbot.com/api/v1/global-fields/Men%C3%BA%20del%20d%C3%ADa" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

keytextoobligatorio
objectsiempre "field_value"obligatorio
nametextoobligatorio
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
valuecualquier valorobligatorio
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "key": "Menú del día",
  "object": "field_value",
  "name": "Menú del día",
  "type": "text",
  "value": null,
  "updated_at": "2026-09-27T11:00:00.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/global-fields/{key}

POST/global-fields/{key}/increment

Sumar o restar a un campo igual para todos sin carreras (cupos, existencias)

Suma en la base, en una sola operación: dos pedidos a la vez nunca pierden una resta. Vacío cuenta como 0; un valor que no es número no se toca (422).

Permiso global_fields:write («Cambiar los datos iguales para todos») · operationId incrementGlobalField · acepta Idempotency-Key

Parámetros

keytexto · en la rutaobligatorio
El campo, por su clave (ciudad) o por su id.
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

bynúmeroobligatorio
Lo que se suma (negativo resta).
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/global-fields/Cupos%20de%20hoy/increment" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Idempotency-Key: incrementGlobalField-A-1043" \
  -H "Content-Type: application/json" \
  -d '{"by":-1}'

Responde 200

keytextoobligatorio
objectsiempre "field_value"obligatorio
nametextoobligatorio
typeuno de estos valoresobligatorio
textnumberdatedatetimebooleanlong_textsingle_choicemultiple_choice
valuecualquier valorobligatorio
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "key": "Cupos de hoy",
  "object": "field_value",
  "name": "Cupos de hoy",
  "type": "number",
  "value": 7,
  "updated_at": "2026-09-27T11:05:00.000Z"
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
422 invalid_field_valueEl valor del campo «…» no es válido.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/global-fields/{key}/increment

Flujos

GET/flows

Los flujos (?status=, ?launchable=true, ?folder=); los de la papelera no salen

Permiso flows:read («Ver flujos») · operationId listFlows

Parámetros

limitnúmero entero · en la dirección
De 1 a 100. Por defecto, 25.
cursortexto · en la dirección
El next_cursor de la página anterior.
statusuno de estos valores · en la dirección
launchableuno de estos valores · en la dirección
true o false.
foldertexto · en la dirección

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/flows" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

idtextoobligatorio
Identificador (uuid).
objectsiempre "flow"obligatorio
nametextoobligatorio
foldertexto o nullobligatorio
statusuno de estos valoresobligatorio
draftactivepausedarchived
launchablesí/no (booleano)obligatorio
not_launchable_reasontexto o nullobligatorio
triggertextoobligatorio
Cómo arranca solo: manual, tag_added, deal_stage_changed, appointment_upcoming, no_reply, ai_function…
inbound_hook_urltexto o nullobligatorio
entry_blockslista de objetoobligatorio
Los bloques del flujo publicado (el de inicio primero): el id de cualquiera sirve de start_at_block.
Ver sus 2 datos
- idtextoobligatorio
- nametextoobligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a",
      "object": "flow",
      "name": "Confirmación de pedido",
      "folder": "Tienda",
      "status": "active",
      "launchable": true,
      "not_launchable_reason": null,
      "trigger": "manual",
      "inbound_hook_url": null,
      "entry_blocks": [
        {
          "id": "n_inicio",
          "name": "Saludo"
        },
        {
          "id": "n_8f2",
          "name": "Pedido enviado"
        }
      ],
      "created_at": "2026-06-01T15:00:00.000Z",
      "updated_at": "2026-09-20T10:12:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

400 invalid_cursorEl cursor no es válido o cambiaron los filtros. Empieza la lista de nuevo.
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
403 module_disabledEsta función no está disponible en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/flows

GET/flows/{id}

Un flujo, con los bloques del dibujo publicado

id es el identificador que va en POST /flows/{id}/runs; también lo copias en Flujos, en el menú ⋯ del flujo → «Copiar ID del flujo». entry_blocks: todos los bloques del dibujo publicado (las notas no), con el de inicio primero; el id de cualquiera sirve de start_at_block. En el editor, el id de un bloque está abajo de su panel.

Permiso flows:read («Ver flujos») · operationId getFlow

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/flows/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "flow"obligatorio
nametextoobligatorio
foldertexto o nullobligatorio
statusuno de estos valoresobligatorio
draftactivepausedarchived
launchablesí/no (booleano)obligatorio
not_launchable_reasontexto o nullobligatorio
triggertextoobligatorio
Cómo arranca solo: manual, tag_added, deal_stage_changed, appointment_upcoming, no_reply, ai_function…
inbound_hook_urltexto o nullobligatorio
entry_blockslista de objetoobligatorio
Los bloques del flujo publicado (el de inicio primero): el id de cualquiera sirve de start_at_block.
Ver sus 2 datos
- idtextoobligatorio
- nametextoobligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
updated_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a",
  "object": "flow",
  "name": "Confirmación de pedido",
  "folder": "Tienda",
  "status": "active",
  "launchable": true,
  "not_launchable_reason": null,
  "trigger": "manual",
  "inbound_hook_url": null,
  "entry_blocks": [
    {
      "id": "n_inicio",
      "name": "Saludo"
    },
    {
      "id": "n_8f2",
      "name": "Pedido enviado"
    }
  ],
  "created_at": "2026-06-01T15:00:00.000Z",
  "updated_at": "2026-09-20T10:12:00.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
403 module_disabledEsta función no está disponible en esta cuenta.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/flows/{id}

POST/flows/{id}/runs

Lanzar un flujo para un contacto, con datos ({{datos.…}})

El flujo tiene que estar activo y publicado: su id sale de GET /flows o de «Copiar ID del flujo» en el menú ⋯ del flujo. Entra por el bloque de inicio o, con start_at_block, por el que elijas. Para un contacto (contact_id) o para el que tenga ese teléfono (contact: lo encuentra o lo crea, y crear pide contacts:write). Se lanza aunque tu equipo esté atendiendo al cliente, como un mensaje masivo: pasar el chat al equipo solo cambia quién contesta lo que el cliente escribe. Si prefieres no escribirle mientras lo atiende una persona, envía "skip_if_team_attending": true: entonces responde 409 conversation_with_team y no lanza nada. La ventana de 24 horas la mira cada bloque que envía: un texto con la ventana cerrada sale por «Falló».

Permiso flows:run («Lanzar flujos») · operationId runFlow · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

contact_idtexto
Identificador (uuid).
contactobjeto
Ver sus 8 datos
- phonetexto
  Teléfono con el indicativo del país. Se aceptan «+», espacios y guiones.
- first_nametexto o null
- last_nametexto o null
- emailtexto o null
- fieldsobjeto
  Los campos por su clave, cada uno con su valor. null vacía el campo.
- tagslista de texto
  Etiquetas por nombre o por id.
- whatsapp_opt_inobjeto
  La prueba del permiso: de dónde viene, qué aceptó el cliente y cuándo.
  Ver sus 3 datos
  - sourceuno de estos valoresobligatorio
    formcheckoutimportin_personother
  - evidencetextoobligatorio
    Lo que aceptó, al pie de la letra, y dónde.
  - captured_attextoobligatorio
    Fecha y hora en ISO 8601 con zona horaria.
- if_existsuno de estos valores
  updatefill_missing
dataobjeto
Datos para el flujo: llegan como {{datos.clave}}. Hasta 50 claves y 32 KB.
start_at_blocktexto
El id de cualquier bloque del flujo publicado (entry_blocks de GET /flows/{id}). Sin él, entra por el bloque de inicio.
allow_repeatsí/no (booleano)
Que entre aunque ya vaya por este flujo.
skip_if_team_attendingsí/no (booleano)
No lanzarlo si tu equipo está atendiendo al cliente (409 conversation_with_team). Sin él, se lanza igual, como un mensaje masivo.
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/flows/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/runs" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"contact_id":"a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1","data":{"pedido":"A-1043","total":"$120.000","guia":"TCC 88213"},"start_at_block":"n_8f2","allow_repeat":false,"idempotency_key":"pedido-A-1043-enviado"}'

Responde 201

idtextoobligatorio
Identificador (uuid).
objectsiempre "flow_run"obligatorio
flow_idtextoobligatorio
Identificador (uuid).
contact_idtextoobligatorio
Identificador (uuid).
stateuno de estos valoresobligatorio
runningwaitingfinishedfailedcancelled
waiting_fortexto o nullobligatorio
wake_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
errortexto o nullobligatorio
started_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
ended_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
stepslista de objetoobligatorio
Ver sus 5 datos
- attextoobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
- block_idtextoobligatorio
- kindtextoobligatorio
- detailtexto o nullobligatorio
- oksí/no (booleano)obligatorio

Ver una respuesta de ejemplo

{
  "id": "2e1d0c9b-8a7f-4e6d-9c5b-4a3f2e1d0c9b",
  "object": "flow_run",
  "flow_id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a",
  "contact_id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "state": "waiting",
  "waiting_for": "reply",
  "wake_at": null,
  "error": null,
  "started_at": "2026-09-27T15:00:00.000Z",
  "ended_at": null,
  "steps": [
    {
      "at": "2026-09-27T15:00:00.120Z",
      "block_id": "n_8f2",
      "kind": "mensaje",
      "detail": "envió «Tu pedido A-1043 va en camino»",
      "ok": true
    }
  ]
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
402 plan_contact_limitLa cuenta llegó a los contactos de su plan. Para agregar más, amplía el plan o suma contactos adicionales.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
403 module_disabledEsta función no está disponible en esta cuenta.
404 not_foundNo existe eso en esta cuenta.
409 conversation_with_teamTu equipo está atendiendo a este cliente y enviaste "skip_if_team_attending": true, así que el flujo no se lanzó.
409 flow_already_runningEl contacto ya va por ese flujo. Envía "allow_repeat": true si quieres que entre otra vez.
409 flow_not_launchableEse flujo no se puede lanzar: no está activo.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
422 invalid_entry_blockEse bloque no existe en el flujo publicado, o es una nota. Usa el id de uno de entry_blocks (GET /flows/{id}).
422 phone_requiredPara crear un contacto hace falta su teléfono.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/flows/{id}/runs

GET/flow-runs/{id}

Un recorrido: en qué va, qué espera, el error y lo que pasó paso a paso

Sirve para entender desde afuera por qué no le llegó algo a alguien.

Permiso flows:read («Ver flujos») · operationId getFlowRun

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/flow-runs/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "flow_run"obligatorio
flow_idtextoobligatorio
Identificador (uuid).
contact_idtextoobligatorio
Identificador (uuid).
stateuno de estos valoresobligatorio
runningwaitingfinishedfailedcancelled
waiting_fortexto o nullobligatorio
wake_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
errortexto o nullobligatorio
started_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
ended_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
stepslista de objetoobligatorio
Ver sus 5 datos
- attextoobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
- block_idtextoobligatorio
- kindtextoobligatorio
- detailtexto o nullobligatorio
- oksí/no (booleano)obligatorio

Ver una respuesta de ejemplo

{
  "id": "2e1d0c9b-8a7f-4e6d-9c5b-4a3f2e1d0c9b",
  "object": "flow_run",
  "flow_id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a",
  "contact_id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "state": "waiting",
  "waiting_for": "reply",
  "wake_at": null,
  "error": null,
  "started_at": "2026-09-27T15:00:00.000Z",
  "ended_at": null,
  "steps": [
    {
      "at": "2026-09-27T15:00:00.120Z",
      "block_id": "n_8f2",
      "kind": "mensaje",
      "detail": "envió «Tu pedido A-1043 va en camino»",
      "ok": true
    }
  ]
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
403 module_disabledEsta función no está disponible en esta cuenta.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/flow-runs/{id}

POST/contacts/{id}/flow-runs/cancel

Cancelar lo que el contacto tenga esperando en sus flujos

Como la acción «Cancelar lo que esté esperando»: cada recorrido cancelado deja escrito por qué. Devuelve cuáles cortó.

Permiso flows:run («Lanzar flujos») · operationId cancelContactFlowRuns · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/contacts/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/flow-runs/cancel" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Idempotency-Key: cancelContactFlowRuns-A-1043"

Responde 200

objectsiempre "flow_runs_cancelled"obligatorio
contact_idtextoobligatorio
cancelled_countnúmero enteroobligatorio
flow_run_idslista de textoobligatorio

Ver una respuesta de ejemplo

{
  "object": "flow_runs_cancelled",
  "contact_id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "cancelled_count": 1,
  "flow_run_ids": [
    "2e1d0c9b-8a7f-4e6d-9c5b-4a3f2e1d0c9b"
  ]
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
403 module_disabledEsta función no está disponible en esta cuenta.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/contacts/{id}/flow-runs/cancel

Mensajes

POST/messages

Enviar un texto, una plantilla o un código de verificación por WhatsApp o por el chat web

Respeta la ventana de 24 horas de cada número. Fuera de ella solo sale una plantilla. Un mensaje de la API no aparta a la IA salvo que envíes "pause_ai": true. Código de verificación. Con "type": "verification_code" envías EL código que tu sistema generó (tú lo creas y lo compruebas; aquí solo se entrega por WhatsApp) con una plantilla de autenticación de «copiar código» aprobada en ese número, en una sola llamada y sin buscar antes al contacto. El código nunca se guarda: en el chat queda «Código de verificación enviado». Sale con la ventana de 24 horas cerrada, como toda plantilla. Como lo pidió la propia persona, no hace falta whatsapp_opt_in y sale aunque haya pedido no recibir más mensajes automáticos; a cambio, cada teléfono recibe como mucho 5 códigos cada 10 minutos y 20 al día (429 con details.limit = verification_codes). El código es texto de 4 a 15 caracteres: letras sin tilde, números y $ # * + ! ? % & _ -. Las plantillas de código se ven en GET /whatsapp/templates con category AUTHENTICATION.

Permiso messages:send («Enviar mensajes») · operationId sendMessage · acepta Idempotency-Key

Parámetros

Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

contact_idtexto
Identificador (uuid).
toobjeto
En vez de contact_id: el contacto de WhatsApp con ese teléfono (en todas sus formas).
Ver sus 4 datos
- phonetextoobligatorio
  Teléfono con el indicativo del país. Se aceptan «+», espacios y guiones.
- nametexto
  Su nombre, si el contacto se crea o no lo tenía.
- emailtexto
- whatsapp_opt_inobjeto
  La prueba del permiso: de dónde viene, qué aceptó el cliente y cuándo.
  Ver sus 3 datos
  - sourceuno de estos valoresobligatorio
    formcheckoutimportin_personother
  - evidencetextoobligatorio
    Lo que aceptó, al pie de la letra, y dónde.
  - captured_attextoobligatorio
    Fecha y hora en ISO 8601 con zona horaria.
create_contactsí/no (booleano)
Con to: lo crea si no existe (pide contacts:write).
channel_idtexto
Por qué número o chat web. Sin él, el de su conversación más reciente o el primer número de WhatsApp de la cuenta.
typeuno de estos valoresobligatorio
texttemplateverification_codemediacontent
textobjeto
Ver sus 2 datos
- bodytextoobligatorio
- preview_urlsí/no (booleano)
  Hoy siempre se muestra la vista previa del primer enlace; apagarla llega en una versión siguiente.
templateobjeto
Ver sus 5 datos
- nametextoobligatorio
- languagetextoobligatorio
- headerobjeto
  El encabezado, si la plantilla lo pide. Un archivo por enlace llega en la próxima versión: hoy sale el que la plantilla tiene de ejemplo en Meta.
  Ver sus 4 datos
  - typeuno de estos valoresobligatorio
    textimagevideodocument
  - texttexto
  - urltexto
  - filenametexto
- bodylista de texto o objeto
  Las variables del mensaje, en orden: {{1}}, {{2}}… En una plantilla con variables con nombre ({{nombre_cliente}}) también van por nombre, como en Meta: {"nombre_cliente": "Ana", "pedido": "A-1"}, en cualquier orden; o en una lista, en el orden de body_variable_names de GET /whatsapp/templates.
- buttonslista de objeto
  Ver sus 2 datos
  - indexnúmero enteroobligatorio
  - texttextoobligatorio
verification_codeobjeto
Con type verification_code: la plantilla y el código a entregar.
Ver sus 3 datos
- templatetextoobligatorio
  El nombre de la plantilla de código de verificación (de «copiar código») aprobada en ese número. Mira GET /whatsapp/templates: category AUTHENTICATION.
- languagetextoobligatorio
  El idioma de esa plantilla, tal como sale en GET /whatsapp/templates: es_CO, es, en_US…
- codetextoobligatorio
  El código que generó tu sistema, como TEXTO (un 004829 como número perdería sus ceros). De 4 a 15 caracteres: letras sin tilde, números y $ # * + ! ? % & _ -. Nunca se guarda.
mediacualquier valor
contentcualquier valor
fill_fieldssí/no (booleano)
Rellenar los {{campos}} con los datos del contacto. Por defecto, sí.
reply_to_message_idtexto
Identificador (uuid).
pause_aisí/no (booleano)
Apartar a la IA (o al flujo del punto de partida) como cuando escribe alguien del equipo, el tiempo elegido en Configuración → Punto de partida. De fábrica (si la cuenta nunca eligió un tiempo) es «Al devolverlo»: sin hora de vuelta, hasta que la devuelvas con la acción return_to_ai o alguien de tu equipo desde la bandeja. Con «Equipo humano» de punto de partida no hace nada: ahí no se pausa nada. Por defecto, no.
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo: Una plantilla

curl -X POST "https://panel.adsmartbot.com/api/v1/messages" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"to":{"phone":"+57 300 123 4567","name":"Ana","whatsapp_opt_in":{"source":"checkout","evidence":"Marcó «Quiero recibir el estado de mi pedido por WhatsApp» en el pago","captured_at":"2026-09-26T14:02:00-05:00"}},"create_contact":true,"type":"template","template":{"name":"pedido_enviado","language":"es","body":["{{nombre_pila}}","A-1043","TCC 88213"]},"pause_ai":false,"idempotency_key":"pedido-A-1043-enviado"}'

Ejemplo: Código de verificación

Entregar por WhatsApp el código que generó tu sistema, en una sola llamada y sin buscar antes al contacto.

curl -X POST "https://panel.adsmartbot.com/api/v1/messages" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Idempotency-Key: sendMessage-A-1043" \
  -H "Content-Type: application/json" \
  -d '{"to":{"phone":"+57 300 123 4567"},"type":"verification_code","verification_code":{"template":"autenticacion_plataforma","language":"es_CO","code":"482913"}}'

Ver su respuesta de ejemplo

{
  "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "object": "message",
  "contact_id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
  "conversation_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "direction": "outbound",
  "type": "template",
  "text": "Código de verificación enviado",
  "template": {
    "name": "autenticacion_plataforma",
    "language": "es_CO",
    "category": "authentication"
  },
  "status": "sent",
  "error": null,
  "sender": {
    "type": "api",
    "id": "0f1e2d3c-4b5a-4968-8776-65a4b3c2d1e0",
    "name": "Portal de clientes"
  },
  "pricing": {
    "category": "authentication",
    "billable": true,
    "free_reason": null
  },
  "created_at": "2026-09-27T15:00:00.000Z"
}

Responde 201

idtextoobligatorio
Identificador (uuid).
objectsiempre "message"obligatorio
contact_idtextoobligatorio
Identificador (uuid).
channel_idtextoobligatorio
Identificador (uuid).
conversation_idtextoobligatorio
Identificador (uuid).
directionuno de estos valoresobligatorio
inboundoutbound
typetextoobligatorio
texttexto o nullobligatorio
templateobjeto o nullobligatorio
Ver sus 3 datos
- nametextoobligatorio
- languagetexto o nullobligatorio
- categorytexto o nullobligatorio
statusuno de estos valoresobligatorio
queuedsentdeliveredreadfailed
errortexto o nullobligatorio
senderobjetoobligatorio
Ver sus 3 datos
- typeuno de estos valoresobligatorio
  contactaiteam_memberapiflow
- idtexto o nullobligatorio
- nametexto o nullobligatorio
pricingobjeto o nullobligatorio
Ver sus 3 datos
- categorytextoobligatorio
- billablesí/no (booleano)obligatorio
- free_reasontexto o nullobligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a",
  "object": "message",
  "contact_id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
  "conversation_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "direction": "outbound",
  "type": "template",
  "text": "Hola Ana, tu pedido A-1043 va en camino con TCC 88213.",
  "template": {
    "name": "pedido_enviado",
    "language": "es",
    "category": "utility"
  },
  "status": "sent",
  "error": null,
  "sender": {
    "type": "api",
    "id": "0f1e2d3c-4b5a-4968-8776-65a4b3c2d1e0",
    "name": "Tienda Shopify"
  },
  "pricing": {
    "category": "utility",
    "billable": true,
    "free_reason": null
  },
  "created_at": "2026-09-27T15:00:00.000Z"
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 invalid_phoneEl teléfono no es válido. Escríbelo con el indicativo del país, por ejemplo +57 300 123 4567.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
402 plan_contact_limitLa cuenta llegó a los contactos de su plan. Para agregar más, amplía el plan o suma contactos adicionales.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 channel_not_availableEse canal no está disponible: no está conectado.
409 contact_blockedEste contacto está bloqueado. Desbloquéalo para escribirle.
409 contact_unsubscribedEste contacto se dio de baja de la publicidad: no se le puede enviar una plantilla de marketing.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
409 whatsapp_opt_in_requiredEste contacto nunca te ha escrito. Para enviarle una plantilla hace falta la prueba de que aceptó recibir WhatsApp: envía whatsapp_opt_in con su fuente y su evidencia.
409 whatsapp_window_closedSe cerraron las 24 horas para escribirle a este contacto por WhatsApp. Envíale una plantilla aprobada para reabrir la conversación.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
422 template_not_foundNo hay una plantilla aprobada llamada «…» en ese idioma en el número elegido.
422 template_parametersLa plantilla «…» lleva ? variables en el mensaje y llegaron ?.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.
502 whatsapp_errorWhatsApp no aceptó el envío: respondió con un error.

https://panel.adsmartbot.com/api/v1/messages

GET/messages/{id}

Un mensaje con su estado (con messages:send, solo los que envió esta misma clave)

Una clave de «solo enviar» puede consultar el estado de lo que ella misma envió sin leer las conversaciones. Lo que pase después (entregado, leído) llega también como aviso.

Permiso: conversations:read («Leer conversaciones») para cualquier mensaje, o messages:send («Enviar mensajes») para los que envió esta misma clave · operationId getMessage

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/messages/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "message"obligatorio
contact_idtextoobligatorio
Identificador (uuid).
channel_idtextoobligatorio
Identificador (uuid).
conversation_idtextoobligatorio
Identificador (uuid).
directionuno de estos valoresobligatorio
inboundoutbound
typetextoobligatorio
texttexto o nullobligatorio
templateobjeto o nullobligatorio
Ver sus 3 datos
- nametextoobligatorio
- languagetexto o nullobligatorio
- categorytexto o nullobligatorio
statusuno de estos valoresobligatorio
queuedsentdeliveredreadfailed
errortexto o nullobligatorio
senderobjetoobligatorio
Ver sus 3 datos
- typeuno de estos valoresobligatorio
  contactaiteam_memberapiflow
- idtexto o nullobligatorio
- nametexto o nullobligatorio
pricingobjeto o nullobligatorio
Ver sus 3 datos
- categorytextoobligatorio
- billablesí/no (booleano)obligatorio
- free_reasontexto o nullobligatorio
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a",
  "object": "message",
  "contact_id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
  "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
  "conversation_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "direction": "outbound",
  "type": "template",
  "text": "Hola Ana, tu pedido A-1043 va en camino con TCC 88213.",
  "template": {
    "name": "pedido_enviado",
    "language": "es",
    "category": "utility"
  },
  "status": "delivered",
  "error": null,
  "sender": {
    "type": "api",
    "id": "0f1e2d3c-4b5a-4968-8776-65a4b3c2d1e0",
    "name": "Tienda Shopify"
  },
  "pricing": {
    "category": "utility",
    "billable": true,
    "free_reason": null
  },
  "created_at": "2026-09-27T15:00:00.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/messages/{id}

GET/whatsapp/templates

Las plantillas aprobadas de cada número (?channel_id= para uno)

Se leen de Meta con una memoria de 5 minutos. Salen también las de autenticación (código de verificación), marcadas con category AUTHENTICATION y su otp_type: no sirven para escribirle a alguien con type template, solo se envían con type verification_code en POST /messages (las de copy_code). Aquí ves su nombre e idioma exactos.

Permiso messages:send («Enviar mensajes») · operationId listWhatsappTemplates

Parámetros

channel_idtexto · en la dirección

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/whatsapp/templates" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

objectsiempre "whatsapp_template"obligatorio
channel_idtextoobligatorio
Identificador (uuid).
nametextoobligatorio
languagetextoobligatorio
categorytextoobligatorio
statussiempre "approved"obligatorio
headerobjeto o nullobligatorio
Ver sus 2 datos
- formattextoobligatorio
- texttexto o nullobligatorio
bodytextoobligatorio
body_variablesnúmero enteroobligatorio
parameter_formatuno de estos valoresobligatorio
El estilo de las variables en Meta: «positional» ({{1}}) o «named» ({{nombre_cliente}}).
positionalnamed
body_variable_nameslista de textoobligatorio
Las variables del mensaje en el orden en que se envían en template.body: «1», «2»… o «nombre_cliente»…
footertexto o nullobligatorio
buttonslista de objetoobligatorio
Ver sus 4 datos
- typetextoobligatorio
- texttextoobligatorio
- urltexto o nullobligatorio
- variablesnúmero enteroobligatorio
otp_typeuno de estos valores o nullobligatorio
Solo en las de autenticación (category AUTHENTICATION): el botón del código. Con type verification_code solo sirven las de copy_code; las otras piden una app de Android propia. Nulo en las demás.
copy_codeone_tapzero_tap
code_expiration_minutesnúmero entero o nullobligatorio
Solo en las de autenticación: los minutos de vida del código que dice el pie («Este código caduca en 10 minutos»). Nulo si no lleva.

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "object": "whatsapp_template",
      "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "name": "pedido_enviado",
      "language": "es",
      "category": "UTILITY",
      "status": "approved",
      "header": null,
      "body": "Hola {{1}}, tu pedido {{2}} va en camino con {{3}}.",
      "body_variables": 3,
      "parameter_format": "positional",
      "body_variable_names": [
        "1",
        "2",
        "3"
      ],
      "footer": null,
      "buttons": [
        {
          "type": "URL",
          "text": "Ver pedido",
          "url": "https://tienda.com/pedidos/{{1}}",
          "variables": 1
        }
      ],
      "otp_type": null,
      "code_expiration_minutes": null
    },
    {
      "object": "whatsapp_template",
      "channel_id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "name": "autenticacion_plataforma",
      "language": "es_CO",
      "category": "AUTHENTICATION",
      "status": "approved",
      "header": null,
      "body": "",
      "body_variables": 1,
      "parameter_format": "positional",
      "body_variable_names": [
        "1"
      ],
      "footer": null,
      "buttons": [
        {
          "type": "OTP",
          "text": "Copiar código",
          "url": null,
          "variables": 0
        }
      ],
      "otp_type": "copy_code",
      "code_expiration_minutes": 10
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 channel_not_availableEse canal no está disponible: no está conectado.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/whatsapp/templates

Avisos

GET/webhooks

Los avisos a otros sistemas que creó esta clave

Solo salen los que creó esta misma clave (o una rotación suya). Los que se crearon en el panel o con otra clave no existen para ella.

Permiso webhooks:manage («Gestionar los avisos a otros sistemas») · operationId listWebhooks

Parámetros

limitnúmero entero · en la dirección
De 1 a 100. Por defecto, 25.
cursortexto · en la dirección
El next_cursor de la página anterior.

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/webhooks" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

idtextoobligatorio
Identificador (uuid).
objectsiempre "webhook"obligatorio
nametextoobligatorio
urltextoobligatorio
La dirección https que recibe los avisos.
descriptiontexto o nullobligatorio
eventslista de textoobligatorio
filtersobjetoobligatorio
statusuno de estos valoresobligatorio
paused: tu sistema no respondió en 3 días (se guarda lo que pase, 7 días). disabled: respondió 410, se revocó la clave o lo apagó el dueño. deleted: solo en la respuesta de DELETE, el aviso ya no existe.
activepauseddisableddeleted
status_reasontexto o nullobligatorio
Por qué está en pausa o apagado, en palabras.
skip_own_eventssí/no (booleano)obligatorio
No recibir los avisos que provocó esta misma clave, aunque en medio haya pasado una regla o un flujo.
api_versiontextoobligatorio
last_success_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
failing_sincetexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
secrettexto
La clave para comprobar la firma (whsec_…). Solo sale al crear y al rotar: guárdala.
previous_secret_expires_attexto o null
Solo al rotar: hasta cuándo la clave anterior sigue firmando a la par.

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "object": "webhook",
      "name": "Zapier: contactos nuevos",
      "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
      "description": null,
      "events": [
        "contact.created",
        "contact.tag_added"
      ],
      "filters": {
        "tag": "VIP"
      },
      "status": "active",
      "status_reason": null,
      "skip_own_events": true,
      "api_version": "v1",
      "last_success_at": "2026-09-26T19:40:01.020Z",
      "failing_since": null,
      "created_at": "2026-09-20T15:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/webhooks

POST/webhooks

Suscribirse a avisos: una dirección https, los tipos y, si quieres, un filtro

La respuesta trae UNA sola vez la clave para comprobar la firma (secret, whsec_…): guárdala. Cada tipo pide el permiso de leerlo: los de contactos, contacts:read; message.received y los de conversaciones, conversations:read («Leer conversaciones», que el paquete «Zapier, Make o n8n» no trae: se marca aparte porque son las charlas con tus clientes); deal.*, crm:read; appointment.*, calendar:read. Como mucho 25 por cuenta y 5 hacia un mismo dominio (Zapier, Make, n8n y Pabbly solo cuentan para el de la cuenta).

Permiso webhooks:manage («Gestionar los avisos a otros sistemas») · operationId createWebhook · acepta Idempotency-Key

Parámetros

Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

urltextoobligatorio
Dirección https pública.
eventslista de uno de estos valoresobligatorio
contact.createdcontact.deletedcontact.tag_addedcontact.tag_removedcontact.field_changedcontact.broadcasts_unsubscribedmessage.receivedconversation.handed_overconversation.returned_to_aiconversation.archivedsequence.subscribedsequence.unsubscribeddeal.createddeal.stage_changeddeal.value_changeddeal.wondeal.lostappointment.bookedappointment.cancelledflow.webhook
nametexto
Un nombre para reconocerlo en el panel. Por defecto, el dominio de la dirección.
descriptiontexto o null
filtersobjeto
Filtros opcionales. Un filtro que no aplica a un tipo no lo frena.
Ver sus 8 datos
- tagtexto
  Solo esa etiqueta (por nombre o por id), en contact.tag_added y contact.tag_removed.
- field_keytexto
  Solo ese campo, en contact.field_changed.
- field_valuetexto
  Solo cuando el campo toma ese valor (sin distinguir mayúsculas).
- pipeline_idtexto
  Solo ese embudo, en deal.*.
- stage_idtexto
  Solo esa etapa, en deal.created y deal.stage_changed.
- calendar_idtexto
  Solo ese calendario, en appointment.*.
- sequence_idtexto
  Solo esa secuencia, en sequence.*.
- channel_idtexto
  Solo ese canal (número de WhatsApp o chat web), en message.received y contact.created.
skip_own_eventssí/no (booleano)
Por defecto true.
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/webhooks" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Idempotency-Key: createWebhook-A-1043" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.zapier.com/hooks/catch/123456/abcdef/","events":["contact.created","contact.tag_added"],"name":"Zapier: contactos nuevos","filters":{"tag":"VIP"}}'

Responde 201

idtextoobligatorio
Identificador (uuid).
objectsiempre "webhook"obligatorio
nametextoobligatorio
urltextoobligatorio
La dirección https que recibe los avisos.
descriptiontexto o nullobligatorio
eventslista de textoobligatorio
filtersobjetoobligatorio
statusuno de estos valoresobligatorio
paused: tu sistema no respondió en 3 días (se guarda lo que pase, 7 días). disabled: respondió 410, se revocó la clave o lo apagó el dueño. deleted: solo en la respuesta de DELETE, el aviso ya no existe.
activepauseddisableddeleted
status_reasontexto o nullobligatorio
Por qué está en pausa o apagado, en palabras.
skip_own_eventssí/no (booleano)obligatorio
No recibir los avisos que provocó esta misma clave, aunque en medio haya pasado una regla o un flujo.
api_versiontextoobligatorio
last_success_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
failing_sincetexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
secrettexto
La clave para comprobar la firma (whsec_…). Solo sale al crear y al rotar: guárdala.
previous_secret_expires_attexto o null
Solo al rotar: hasta cuándo la clave anterior sigue firmando a la par.

Ver una respuesta de ejemplo

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "object": "webhook",
  "name": "Zapier: contactos nuevos",
  "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
  "description": null,
  "events": [
    "contact.created",
    "contact.tag_added"
  ],
  "filters": {
    "tag": "VIP"
  },
  "status": "active",
  "status_reason": null,
  "skip_own_events": true,
  "api_version": "v1",
  "last_success_at": null,
  "failing_since": null,
  "created_at": "2026-09-20T15:00:00.000Z",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
409 subscription_limitLlegaste al máximo de avisos a otros sistemas en esta cuenta.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/webhooks

GET/webhooks/{id}

Un aviso a otro sistema

Permiso webhooks:manage («Gestionar los avisos a otros sistemas») · operationId getWebhook

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/webhooks/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "webhook"obligatorio
nametextoobligatorio
urltextoobligatorio
La dirección https que recibe los avisos.
descriptiontexto o nullobligatorio
eventslista de textoobligatorio
filtersobjetoobligatorio
statusuno de estos valoresobligatorio
paused: tu sistema no respondió en 3 días (se guarda lo que pase, 7 días). disabled: respondió 410, se revocó la clave o lo apagó el dueño. deleted: solo en la respuesta de DELETE, el aviso ya no existe.
activepauseddisableddeleted
status_reasontexto o nullobligatorio
Por qué está en pausa o apagado, en palabras.
skip_own_eventssí/no (booleano)obligatorio
No recibir los avisos que provocó esta misma clave, aunque en medio haya pasado una regla o un flujo.
api_versiontextoobligatorio
last_success_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
failing_sincetexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
secrettexto
La clave para comprobar la firma (whsec_…). Solo sale al crear y al rotar: guárdala.
previous_secret_expires_attexto o null
Solo al rotar: hasta cuándo la clave anterior sigue firmando a la par.

Ver una respuesta de ejemplo

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "object": "webhook",
  "name": "Zapier: contactos nuevos",
  "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
  "description": null,
  "events": [
    "contact.created",
    "contact.tag_added"
  ],
  "filters": {
    "tag": "VIP"
  },
  "status": "active",
  "status_reason": null,
  "skip_own_events": true,
  "api_version": "v1",
  "last_success_at": "2026-09-26T19:40:01.020Z",
  "failing_since": null,
  "created_at": "2026-09-20T15:00:00.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/webhooks/{id}

PATCH/webhooks/{id}

Cambiar la dirección, los tipos o el filtro de un aviso

Lo que no se envía no se toca. Cambiar los tipos vuelve a pedir el permiso de leer cada uno.

Permiso webhooks:manage («Gestionar los avisos a otros sistemas») · operationId updateWebhook · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Cuerpo (JSON)

urltexto
eventslista de uno de estos valores
contact.createdcontact.deletedcontact.tag_addedcontact.tag_removedcontact.field_changedcontact.broadcasts_unsubscribedmessage.receivedconversation.handed_overconversation.returned_to_aiconversation.archivedsequence.subscribedsequence.unsubscribeddeal.createddeal.stage_changeddeal.value_changeddeal.wondeal.lostappointment.bookedappointment.cancelledflow.webhook
nametexto
descriptiontexto o null
filtersobjeto
Filtros opcionales. Un filtro que no aplica a un tipo no lo frena.
Ver sus 8 datos
- tagtexto
  Solo esa etiqueta (por nombre o por id), en contact.tag_added y contact.tag_removed.
- field_keytexto
  Solo ese campo, en contact.field_changed.
- field_valuetexto
  Solo cuando el campo toma ese valor (sin distinguir mayúsculas).
- pipeline_idtexto
  Solo ese embudo, en deal.*.
- stage_idtexto
  Solo esa etapa, en deal.created y deal.stage_changed.
- calendar_idtexto
  Solo ese calendario, en appointment.*.
- sequence_idtexto
  Solo esa secuencia, en sequence.*.
- channel_idtexto
  Solo ese canal (número de WhatsApp o chat web), en message.received y contact.created.
skip_own_eventssí/no (booleano)
idempotency_keytexto
Igual que la cabecera Idempotency-Key, para herramientas que no dejan poner cabeceras.

Ejemplo

curl -X PATCH "https://panel.adsmartbot.com/api/v1/webhooks/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"events":["contact.created"],"filters":{}}'

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "webhook"obligatorio
nametextoobligatorio
urltextoobligatorio
La dirección https que recibe los avisos.
descriptiontexto o nullobligatorio
eventslista de textoobligatorio
filtersobjetoobligatorio
statusuno de estos valoresobligatorio
paused: tu sistema no respondió en 3 días (se guarda lo que pase, 7 días). disabled: respondió 410, se revocó la clave o lo apagó el dueño. deleted: solo en la respuesta de DELETE, el aviso ya no existe.
activepauseddisableddeleted
status_reasontexto o nullobligatorio
Por qué está en pausa o apagado, en palabras.
skip_own_eventssí/no (booleano)obligatorio
No recibir los avisos que provocó esta misma clave, aunque en medio haya pasado una regla o un flujo.
api_versiontextoobligatorio
last_success_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
failing_sincetexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
secrettexto
La clave para comprobar la firma (whsec_…). Solo sale al crear y al rotar: guárdala.
previous_secret_expires_attexto o null
Solo al rotar: hasta cuándo la clave anterior sigue firmando a la par.

Ver una respuesta de ejemplo

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "object": "webhook",
  "name": "Zapier: contactos nuevos",
  "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
  "description": null,
  "events": [
    "contact.created"
  ],
  "filters": {},
  "status": "active",
  "status_reason": null,
  "skip_own_events": true,
  "api_version": "v1",
  "last_success_at": "2026-09-26T19:40:01.020Z",
  "failing_since": null,
  "created_at": "2026-09-20T15:00:00.000Z"
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
409 subscription_limitLlegaste al máximo de avisos a otros sistemas en esta cuenta.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/webhooks/{id}

DELETE/webhooks/{id}

Borrar un aviso a otro sistema

Deja de avisar al instante y se borra su registro de entregas. Responde con el aviso tal como estaba, con status «deleted».

Permiso webhooks:manage («Gestionar los avisos a otros sistemas») · operationId deleteWebhook · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Ejemplo

curl -X DELETE "https://panel.adsmartbot.com/api/v1/webhooks/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "webhook"obligatorio
nametextoobligatorio
urltextoobligatorio
La dirección https que recibe los avisos.
descriptiontexto o nullobligatorio
eventslista de textoobligatorio
filtersobjetoobligatorio
statusuno de estos valoresobligatorio
paused: tu sistema no respondió en 3 días (se guarda lo que pase, 7 días). disabled: respondió 410, se revocó la clave o lo apagó el dueño. deleted: solo en la respuesta de DELETE, el aviso ya no existe.
activepauseddisableddeleted
status_reasontexto o nullobligatorio
Por qué está en pausa o apagado, en palabras.
skip_own_eventssí/no (booleano)obligatorio
No recibir los avisos que provocó esta misma clave, aunque en medio haya pasado una regla o un flujo.
api_versiontextoobligatorio
last_success_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
failing_sincetexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
secrettexto
La clave para comprobar la firma (whsec_…). Solo sale al crear y al rotar: guárdala.
previous_secret_expires_attexto o null
Solo al rotar: hasta cuándo la clave anterior sigue firmando a la par.

Ver una respuesta de ejemplo

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "object": "webhook",
  "name": "Zapier: contactos nuevos",
  "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
  "description": null,
  "events": [
    "contact.created",
    "contact.tag_added"
  ],
  "filters": {
    "tag": "VIP"
  },
  "status": "deleted",
  "status_reason": null,
  "skip_own_events": true,
  "api_version": "v1",
  "last_success_at": "2026-09-26T19:40:01.020Z",
  "failing_since": null,
  "created_at": "2026-09-20T15:00:00.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/webhooks/{id}

POST/webhooks/{id}/test

Enviar un aviso de prueba de verdad, firmado, del tipo que pidas

Sale en el momento, con datos de ejemplo y "test": true. Queda en las entregas, pero no se reintenta.

Permiso webhooks:manage («Gestionar los avisos a otros sistemas») · operationId testWebhook

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).

Cuerpo (JSON)

typeuno de estos valores
Por defecto, ping.
contact.createdcontact.deletedcontact.tag_addedcontact.tag_removedcontact.field_changedcontact.broadcasts_unsubscribedmessage.receivedconversation.handed_overconversation.returned_to_aiconversation.archivedsequence.subscribedsequence.unsubscribeddeal.createddeal.stage_changeddeal.value_changeddeal.wondeal.lostappointment.bookedappointment.cancelledflow.webhookping

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/webhooks/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/test" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"type":"contact.created"}'

Responde 200

objectsiempre "webhook_test"obligatorio
oksí/no (booleano)obligatorio
status_codenúmero entero o nullobligatorio
duration_msnúmero enteroobligatorio
errortexto o nullobligatorio
deliveryobjetoobligatorio
Una entrega de un aviso a una dirección, con su último intento.
Ver sus 14 datos
- idtextoobligatorio
  Identificador (uuid).
- objectsiempre "webhook_delivery"obligatorio
- webhook_idtextoobligatorio
  Identificador (uuid).
- event_idtextoobligatorio
  El id del aviso: el mismo webhook-id en cada intento.
- event_typetextoobligatorio
- statusuno de estos valoresobligatorio
  pendingsendingretryingdeliveredfailedcancelledblocked
- attemptsnúmero enteroobligatorio
- next_attempt_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
- last_status_codenúmero entero o nullobligatorio
- last_errortexto o nullobligatorio
  Qué pasó, en palabras.
- duration_msnúmero entero o nullobligatorio
- response_excerpttexto o nullobligatorio
  Hasta 300 caracteres de lo que respondió tu sistema (solo texto o JSON).
- created_attextoobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
- delivered_attexto o nullobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "object": "webhook_test",
  "ok": true,
  "status_code": 200,
  "duration_ms": 184,
  "error": null,
  "delivery": {
    "id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
    "object": "webhook_delivery",
    "webhook_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "event_id": "3f6c2a0e-5b7d-4c1e-9a2f-7d1b0c9e8a41",
    "event_type": "contact.created",
    "status": "delivered",
    "attempts": 1,
    "next_attempt_at": null,
    "last_status_code": 200,
    "last_error": null,
    "duration_ms": 184,
    "response_excerpt": "{\"status\":\"success\"}",
    "created_at": "2026-09-26T19:40:00.200Z",
    "delivered_at": "2026-09-26T19:40:00.384Z"
  }
}

Errores posibles

400 invalid_jsonEl cuerpo no es un JSON válido.
400 invalid_parameterEl dato «…» no es válido: revisa su formato.
400 missing_parameterFalta el dato «…».
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
413 payload_too_largeEl cuerpo pasa de 1 MB.
415 unsupported_media_typeEnvía el cuerpo como JSON (Content-Type: application/json).
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/webhooks/{id}/test

POST/webhooks/{id}/rotate-secret

Cambiar la clave de la firma (la vieja sigue valiendo 24 horas)

Durante 24 horas cada aviso lleva dos firmas (la nueva y la vieja): cambia la clave en tu sistema sin perder avisos. Repetirla es seguro: cada vez da una clave nueva y la anterior sigue firmando 24 horas.

Permiso webhooks:manage («Gestionar los avisos a otros sistemas») · operationId rotateWebhookSecret

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/webhooks/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/rotate-secret" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "webhook"obligatorio
nametextoobligatorio
urltextoobligatorio
La dirección https que recibe los avisos.
descriptiontexto o nullobligatorio
eventslista de textoobligatorio
filtersobjetoobligatorio
statusuno de estos valoresobligatorio
paused: tu sistema no respondió en 3 días (se guarda lo que pase, 7 días). disabled: respondió 410, se revocó la clave o lo apagó el dueño. deleted: solo en la respuesta de DELETE, el aviso ya no existe.
activepauseddisableddeleted
status_reasontexto o nullobligatorio
Por qué está en pausa o apagado, en palabras.
skip_own_eventssí/no (booleano)obligatorio
No recibir los avisos que provocó esta misma clave, aunque en medio haya pasado una regla o un flujo.
api_versiontextoobligatorio
last_success_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
failing_sincetexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
secrettexto
La clave para comprobar la firma (whsec_…). Solo sale al crear y al rotar: guárdala.
previous_secret_expires_attexto o null
Solo al rotar: hasta cuándo la clave anterior sigue firmando a la par.

Ver una respuesta de ejemplo

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "object": "webhook",
  "name": "Zapier: contactos nuevos",
  "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
  "description": null,
  "events": [
    "contact.created",
    "contact.tag_added"
  ],
  "filters": {
    "tag": "VIP"
  },
  "status": "active",
  "status_reason": null,
  "skip_own_events": true,
  "api_version": "v1",
  "last_success_at": "2026-09-26T19:40:01.020Z",
  "failing_since": null,
  "created_at": "2026-09-20T15:00:00.000Z",
  "secret": "whsec_2x8Jc3kqPq9n1zB7yVf4Tn0mR6sLh5dE",
  "previous_secret_expires_at": "2026-09-27T19:40:00.000Z"
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/webhooks/{id}/rotate-secret

POST/webhooks/{id}/enable

Volver a encender un aviso en pausa

Lo guardado mientras estuvo en pausa (hasta 7 días) sale en orden, a 10 por segundo.

Permiso webhooks:manage («Gestionar los avisos a otros sistemas») · operationId enableWebhook · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/webhooks/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/enable" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Idempotency-Key: enableWebhook-A-1043"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "webhook"obligatorio
nametextoobligatorio
urltextoobligatorio
La dirección https que recibe los avisos.
descriptiontexto o nullobligatorio
eventslista de textoobligatorio
filtersobjetoobligatorio
statusuno de estos valoresobligatorio
paused: tu sistema no respondió en 3 días (se guarda lo que pase, 7 días). disabled: respondió 410, se revocó la clave o lo apagó el dueño. deleted: solo en la respuesta de DELETE, el aviso ya no existe.
activepauseddisableddeleted
status_reasontexto o nullobligatorio
Por qué está en pausa o apagado, en palabras.
skip_own_eventssí/no (booleano)obligatorio
No recibir los avisos que provocó esta misma clave, aunque en medio haya pasado una regla o un flujo.
api_versiontextoobligatorio
last_success_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
failing_sincetexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
secrettexto
La clave para comprobar la firma (whsec_…). Solo sale al crear y al rotar: guárdala.
previous_secret_expires_attexto o null
Solo al rotar: hasta cuándo la clave anterior sigue firmando a la par.

Ver una respuesta de ejemplo

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "object": "webhook",
  "name": "Zapier: contactos nuevos",
  "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
  "description": null,
  "events": [
    "contact.created",
    "contact.tag_added"
  ],
  "filters": {
    "tag": "VIP"
  },
  "status": "active",
  "status_reason": null,
  "skip_own_events": true,
  "api_version": "v1",
  "last_success_at": "2026-09-26T19:40:01.020Z",
  "failing_since": null,
  "created_at": "2026-09-20T15:00:00.000Z"
}

Errores posibles

400 invalid_parameterEl dato «…» no es válido: revisa su formato.
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/webhooks/{id}/enable

GET/webhooks/{id}/deliveries

Las entregas de un aviso de los últimos 30 días

Las más nuevas primero. Solo las de tipos que esta clave puede leer hoy.

Permiso webhooks:manage («Gestionar los avisos a otros sistemas») · operationId listWebhookDeliveries

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
limitnúmero entero · en la dirección
De 1 a 100. Por defecto, 25.
cursortexto · en la dirección
El next_cursor de la página anterior.
only_errorsuno de estos valores · en la dirección
true: solo las que fallaron, se están reintentando o se frenaron.

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/webhooks/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/deliveries" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

idtextoobligatorio
Identificador (uuid).
objectsiempre "webhook_delivery"obligatorio
webhook_idtextoobligatorio
Identificador (uuid).
event_idtextoobligatorio
El id del aviso: el mismo webhook-id en cada intento.
event_typetextoobligatorio
statusuno de estos valoresobligatorio
pendingsendingretryingdeliveredfailedcancelledblocked
attemptsnúmero enteroobligatorio
next_attempt_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
last_status_codenúmero entero o nullobligatorio
last_errortexto o nullobligatorio
Qué pasó, en palabras.
duration_msnúmero entero o nullobligatorio
response_excerpttexto o nullobligatorio
Hasta 300 caracteres de lo que respondió tu sistema (solo texto o JSON).
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
delivered_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
      "object": "webhook_delivery",
      "webhook_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "event_id": "3f6c2a0e-5b7d-4c1e-9a2f-7d1b0c9e8a41",
      "event_type": "contact.created",
      "status": "delivered",
      "attempts": 1,
      "next_attempt_at": null,
      "last_status_code": 200,
      "last_error": null,
      "duration_ms": 184,
      "response_excerpt": "{\"status\":\"success\"}",
      "created_at": "2026-09-26T19:40:00.200Z",
      "delivered_at": "2026-09-26T19:40:00.384Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

400 invalid_cursorEl cursor no es válido o cambiaron los filtros. Empieza la lista de nuevo.
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/webhooks/{id}/deliveries

POST/webhooks/{id}/deliveries/{delivery_id}/retry

Volver a enviar exactamente el mismo aviso

Mismo id y mismos datos: tu sistema lo reconoce si ya lo tenía. Sale en los próximos segundos.

Permiso webhooks:manage («Gestionar los avisos a otros sistemas») · operationId retryWebhookDelivery · acepta Idempotency-Key

Parámetros

idtexto · en la rutaobligatorio
El id (uuid).
delivery_idtexto · en la rutaobligatorio
El id de la entrega.
Idempotency-Keytexto · cabecera
Repetir con la misma clave devuelve la misma respuesta sin volver a hacerlo (24 horas).

Ejemplo

curl -X POST "https://panel.adsmartbot.com/api/v1/webhooks/a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1/deliveries/1b4e28ba-2fa1-41d2-883f-0016d3cca427/retry" \
  -H "Authorization: Bearer $CLAVE_API" \
  -H "Idempotency-Key: retryWebhookDelivery-A-1043"

Responde 200

idtextoobligatorio
Identificador (uuid).
objectsiempre "webhook_delivery"obligatorio
webhook_idtextoobligatorio
Identificador (uuid).
event_idtextoobligatorio
El id del aviso: el mismo webhook-id en cada intento.
event_typetextoobligatorio
statusuno de estos valoresobligatorio
pendingsendingretryingdeliveredfailedcancelledblocked
attemptsnúmero enteroobligatorio
next_attempt_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
last_status_codenúmero entero o nullobligatorio
last_errortexto o nullobligatorio
Qué pasó, en palabras.
duration_msnúmero entero o nullobligatorio
response_excerpttexto o nullobligatorio
Hasta 300 caracteres de lo que respondió tu sistema (solo texto o JSON).
created_attextoobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.
delivered_attexto o nullobligatorio
Fecha y hora en ISO 8601, UTC, con milisegundos.

Ver una respuesta de ejemplo

{
  "id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
  "object": "webhook_delivery",
  "webhook_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "event_id": "3f6c2a0e-5b7d-4c1e-9a2f-7d1b0c9e8a41",
  "event_type": "contact.created",
  "status": "pending",
  "attempts": 1,
  "next_attempt_at": "2026-09-26T19:45:00.000Z",
  "last_status_code": 200,
  "last_error": null,
  "duration_ms": 184,
  "response_excerpt": "{\"status\":\"success\"}",
  "created_at": "2026-09-26T19:40:00.200Z",
  "delivered_at": null
}

Errores posibles

400 invalid_parameterEl dato «…» no es válido: revisa su formato.
401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
403 insufficient_permissionsEsta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.
404 not_foundNo existe eso en esta cuenta.
409 idempotency_in_progressEsa petición todavía se está haciendo. Vuelve a intentar en unos segundos.
422 idempotency_key_reusedYa usaste esa Idempotency-Key con otros datos.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/webhooks/{id}/deliveries/{delivery_id}/retry

GET/event-types

El catálogo de avisos, con un ejemplo de cada uno

Con cualquier clave válida. Zapier y Make lo usan para armar sus pantallas: cada ejemplo trae los mismos campos que el aviso de verdad.

Cualquier clave válida · operationId listEventTypes

Ejemplo

curl -X GET "https://panel.adsmartbot.com/api/v1/event-types" \
  -H "Authorization: Bearer $CLAVE_API"

Responde 200: una lista; cada elemento de data trae

objectsiempre "event_type"obligatorio
typetextoobligatorio
nametextoobligatorio
Como se llama en el panel.
grouptextoobligatorio
descriptiontextoobligatorio
availablesí/no (booleano)obligatorio
Si ya se puede elegir. Los demás llegan en una versión próxima.
phasetextoobligatorio
scopeslista de textoobligatorio
Los permisos de lectura que tiene que tener la clave para recibirlo.
filterslista de textoobligatorio
exampleobjeto o nullobligatorio
Lo que recibe tu sistema en cada aviso (POST con JSON, firmado con Standard Webhooks).
Ver sus 10 datos
- idtextoobligatorio
  El mismo en cada reintento: es el webhook-id de la firma.
- objectsiempre "event"obligatorio
- typetextoobligatorio
- api_versiontextoobligatorio
- created_attextoobligatorio
  Fecha y hora en ISO 8601, UTC, con milisegundos.
- accountobjetoobligatorio
  Ver sus 2 datos
  - idtextoobligatorio
    Identificador (uuid).
  - nametextoobligatorio
- actorobjetoobligatorio
  Quién lo hizo.
  Ver sus 3 datos
  - typeuno de estos valoresobligatorio
    contactaiflowruleteam_memberapi_keysystem
  - idtexto o nullobligatorio
  - nametexto o nullobligatorio
- causeobjeto o nullobligatorio
  Qué empezó la cadena desde afuera y cuántas reglas y flujos lleva. Nula si nada de afuera la empezó.
  Ver sus 2 datos
  - originobjetoobligatorio
    Ver sus 3 datos
    typeuno de estos valoresobligatorio
    api_keyinbound_hook
    idtextoobligatorio
    Identificador (uuid).
    nametexto o nullobligatorio
  - hopsnúmero enteroobligatorio
- dataobjetoobligatorio
- testsiempre true
  Solo en los avisos de «Probar».

Ver una respuesta de ejemplo

{
  "object": "list",
  "data": [
    {
      "object": "event_type",
      "type": "contact.tag_added",
      "name": "Se le agrega una etiqueta",
      "group": "Contacto",
      "description": "Desde cualquier sitio: la bandeja, Contactos, un flujo, una regla o la API.",
      "available": true,
      "phase": "1a",
      "scopes": [
        "contacts:read"
      ],
      "filters": [
        "tag"
      ],
      "example": {
        "id": "3f6c2a0e-5b7d-4c1e-9a2f-7d1b0c9e8a41",
        "object": "event",
        "type": "contact.tag_added",
        "api_version": "v1",
        "created_at": "2026-09-26T19:40:00.123Z",
        "account": {
          "id": "9b1d7c20-3e4f-4a5b-8c6d-0e1f2a3b4c5d",
          "name": "Peluquería Ana"
        },
        "actor": {
          "type": "team_member",
          "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
          "name": "Laura"
        },
        "cause": {
          "origin": {
            "type": "api_key",
            "id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
            "name": "Tienda"
          },
          "hops": 0
        },
        "data": {
          "contact": {
            "id": "a4f2c0de-8b1e-4c51-9a7a-2f1d9c0b77e1",
            "object": "contact",
            "channel": "whatsapp",
            "first_name": "Ana",
            "last_name": "Gómez",
            "full_name": "Ana Gómez",
            "phone": "+573001234567",
            "email": "ana@correo.com",
            "email_verified": false,
            "whatsapp": {
              "wa_id": "573001234567",
              "bsuid": null,
              "username": null
            },
            "profile_pic_url": null,
            "locale": null,
            "timezone": "America/Bogota",
            "origin": "direct_message",
            "tags": [
              {
                "id": "b8c9d0e1-f2a3-4b4c-9d5e-6f7a8b9c0d1e",
                "name": "VIP"
              }
            ],
            "fields": {
              "Ciudad": "Cali",
              "Talla": "M"
            },
            "broadcasts_subscribed": true,
            "broadcasts_opt_out": null,
            "whatsapp_opt_in": null,
            "email_unsubscribed": false,
            "blocked": false,
            "interactions_count": 12,
            "has_written": true,
            "last_inbound_at": "2026-09-26T19:39:58.000Z",
            "last_outbound_at": "2026-09-26T19:35:10.000Z",
            "whatsapp_windows": [
              {
                "channel_id": "c7e1b2a3-4d5e-4f60-8a71-b2c3d4e5f607",
                "open": true,
                "closes_at": "2026-09-27T19:39:58.000Z"
              }
            ],
            "created_at": "2026-09-01T10:00:00.000Z",
            "updated_at": "2026-09-26T19:40:00.120Z"
          },
          "tag": {
            "id": "b8c9d0e1-f2a3-4b4c-9d5e-6f7a8b9c0d1e",
            "name": "VIP"
          }
        }
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores posibles

401 expired_api_keyEsta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.
401 invalid_api_keyEsa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.
401 missing_api_keyFalta la clave de acceso. Envíala en la cabecera Authorization: Bearer …
401 revoked_api_keyEsta clave de acceso se revocó el día en que se revocó.
402 account_payment_requiredLa cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.
429 rate_limitedDemasiadas peticiones. Vuelve a intentar en unos segundos.
500 internal_errorAlgo falló de nuestro lado. Quedó anotado con el número de esta petición.

https://panel.adsmartbot.com/api/v1/event-types