Identificadores
Cómo son los ids de la API (texto con un prefijo que dice el tipo), la tabla de prefijos y qué pasa con un id inválido.
Desde el 16-11-2026, todo id que la API devuelve o acepta es un id opaco: un texto con un prefijo que dice de qué es. Por ejemplo, ctc_ABsza6Ialu1BCUyPFZ8WJvV es el id de un contacto.
Cómo es
- Tiene tres partes: un prefijo de tres letras (
ctc), un guion bajo y 23 caracteres letras y números (el primero indica la versión de la clave con la que se armó; el resto es el id propiamente dicho). - El prefijo dice el tipo. Un
dev_…es un número de WhatsApp, unctc_…un contacto, unmsg_…un mensaje. - Se usa tal como llega: guárdalo como texto, pásalo igual en la ruta, en la query o en el cuerpo, y compáralo como texto. No lo interpretes ni lo armes: no tiene un orden, no se puede deducir de otro y su forma puede cambiar sin que cambie lo que identifica.
- Los ids que siguen como estaban: el
uidde un grupo, eluuidde una campaña, eluidde un mensaje, eluidouuidde una acción de grupo, los ids de las cuentas de WhatsApp Business (WABA) yworkspace_id. Ninguno lleva prefijo.
Dónde conseguir el id
- Por la API: cada recurso trae su
idal listarlo o crearlo (por ejemplo, Listar números trae elidde cada número). Los eventos de los webhooks traen los mismos ids. - En el panel de Funnelchat: el panel sigue mostrando los ids de siempre, pero también muestra el «ID para la API», con un botón para copiarlo, en tus números de WhatsApp, en Desarrolladores y en las suscripciones de webhooks. Ese es el que va en la API.
Qué pasa con un id que no sirve
El cambio es directo: no hay un período en el que la API acepte los dos formatos. Desde la activación, un número entero en una ruta o en un cuerpo responde 404 not_found. En un cuerpo, lo mismo que un id que no existe en esa ruta.
- Un id mal formado, o de otro tipo que el que pide esa ruta (un
ctc_…donde va undev_…), responde igual que uno que no existe:404 not_found. - Un
404no dice por qué: puede ser un id viejo, mal copiado, de otro tipo, de otra cuenta o de otro workspace. - Si migras un sistema que guardaba los enteros, vuelve a pedir los ids a la API (por ejemplo, listando) y guarda los nuevos; no hay forma de convertir un entero en su id opaco.
Prefijos
Los de las especificaciones de accounts, communities y conversations. «Dónde» son algunos de los campos y parámetros que los llevan (la especificación de cada llamada dice cuáles).
| Prefijo | Qué identifica | Dónde |
|---|---|---|
acg_ | Un grupo dentro de una acción de campaña | id de cada grupo de la acción |
act_ | Una acción de campaña | id, {action} |
ald_ | Un destino de alertas | id, {id} de los destinos |
bcs_ | Una difusión | broadcast_id, broadcast_ids, {broadcast} |
cev_ | Un evento de conexión de un número | id |
clk_ | Un registro de clics (estadísticas) | id de cada registro |
cmp_ | Una campaña | campaign_id, campaign_ids, {campaign} |
cnd_ | Una condición de campaña | id |
ctc_ | Un contacto | contact_id, contactId, contact_ids, {contact} |
dev_ | Un número de WhatsApp | device_id, deviceId, device_ids, same_number_as, {device} |
dlv_ | Una entrega de webhook | delivery_id, id de la entrega |
dom_ | Un dominio propio | id, {customDomain} |
fdr_ | Una carpeta (de difusiones, de flujos o de envíos programados) | folder_id, parent_id, {folder} |
fld_ | Un campo personalizado | custom_field_ids, customFieldId, {customField} |
flw_ | Un flujo | flow_id, flow_ids, {flow} |
fre_ | Un efecto de la respuesta a un formulario | id dentro de effects |
frm_ | Un formulario (su familia: todas sus versiones) | family_id, familyId |
frs_ | Una respuesta a un formulario | run_id, {runId} |
frv_ | Una versión de un formulario | id, version_id, whatsapp_form_id |
grc_ | Un período de gracia de contactos activos | grace_period_id |
grp_ | Un grupo, en las listas de communities que lo identifican con id | group_id, group_ids, redirect_group_id |
knb_ | Un tablero | kanban_setting_id, {kanbanSetting} |
lnk_ | Un link de alta | connect_link_id, id, {link} |
msg_ | Un mensaje | message_id, id, {message} |
mtp_ | Una plantilla de respuesta de un envío programado | message_template_id |
not_ | Una nota de un contacto | id, {note} |
opl_ | Un plan de operación de una campaña | id, {plan} |
pip_ | Un pipeline de una campaña | {pipeline} |
pln_ | Un plan de la cuenta | plan_id, selected_plan_id |
prt_ | Un participante | id |
qrp_ | Una respuesta rápida | id, {quickReply} |
run_ | Una ejecución de un flujo en un contacto | automation_run_id, {contactFlowId} |
sal_ | Una venta | id |
smg_ | Un envío programado | id, {scheduledMessage} |
snd_ | Una plantilla de un envío programado a grupos | template_id |
stg_ | Una etapa de un tablero | stage_id, kanban_stage_ids, {stage} |
tag_ | Una etiqueta | tag_id, tag_ids, {tag} |
tkt_ | Un ticket | ticketId, id, {id} de los tickets |
tpl_ | Una plantilla de mensaje | template_id, {template} |
usr_ | Un usuario del equipo | user_id, owner_id, adviser_id, {user} |
Ten en cuenta
- Cada id vale solo para su tipo: el
idde un contacto no sirve donde va el de un número. - Los ejemplos de esta documentación usan ids de ejemplo con el prefijo correcto; no son ids reales de ninguna cuenta.
- Si un cuerpo o un evento trae un prefijo que no está en la tabla, trátalo igual: como texto que no se interpreta.