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, un ctc_… un contacto, un msg_… 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 uid de un grupo, el uuid de una campaña, el uid de un mensaje, el uid o uuid de una acción de grupo, los ids de las cuentas de WhatsApp Business (WABA) y workspace_id. Ninguno lleva prefijo.

Dónde conseguir el id

  • Por la API: cada recurso trae su id al listarlo o crearlo (por ejemplo, Listar números trae el id de 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 un dev_…), responde igual que uno que no existe: 404 not_found.
  • Un 404 no 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).

PrefijoQué identificaDónde
acg_Un grupo dentro de una acción de campañaid de cada grupo de la acción
act_Una acción de campañaid, {action}
ald_Un destino de alertasid, {id} de los destinos
bcs_Una difusiónbroadcast_id, broadcast_ids, {broadcast}
cev_Un evento de conexión de un númeroid
clk_Un registro de clics (estadísticas)id de cada registro
cmp_Una campañacampaign_id, campaign_ids, {campaign}
cnd_Una condición de campañaid
ctc_Un contactocontact_id, contactId, contact_ids, {contact}
dev_Un número de WhatsAppdevice_id, deviceId, device_ids, same_number_as, {device}
dlv_Una entrega de webhookdelivery_id, id de la entrega
dom_Un dominio propioid, {customDomain}
fdr_Una carpeta (de difusiones, de flujos o de envíos programados)folder_id, parent_id, {folder}
fld_Un campo personalizadocustom_field_ids, customFieldId, {customField}
flw_Un flujoflow_id, flow_ids, {flow}
fre_Un efecto de la respuesta a un formularioid dentro de effects
frm_Un formulario (su familia: todas sus versiones)family_id, familyId
frs_Una respuesta a un formulariorun_id, {runId}
frv_Una versión de un formularioid, version_id, whatsapp_form_id
grc_Un período de gracia de contactos activosgrace_period_id
grp_Un grupo, en las listas de communities que lo identifican con idgroup_id, group_ids, redirect_group_id
knb_Un tablerokanban_setting_id, {kanbanSetting}
lnk_Un link de altaconnect_link_id, id, {link}
msg_Un mensajemessage_id, id, {message}
mtp_Una plantilla de respuesta de un envío programadomessage_template_id
not_Una nota de un contactoid, {note}
opl_Un plan de operación de una campañaid, {plan}
pip_Un pipeline de una campaña{pipeline}
pln_Un plan de la cuentaplan_id, selected_plan_id
prt_Un participanteid
qrp_Una respuesta rápidaid, {quickReply}
run_Una ejecución de un flujo en un contactoautomation_run_id, {contactFlowId}
sal_Una ventaid
smg_Un envío programadoid, {scheduledMessage}
snd_Una plantilla de un envío programado a grupostemplate_id
stg_Una etapa de un tablerostage_id, kanban_stage_ids, {stage}
tag_Una etiquetatag_id, tag_ids, {tag}
tkt_Un ticketticketId, id, {id} de los tickets
tpl_Una plantilla de mensajetemplate_id, {template}
usr_Un usuario del equipouser_id, owner_id, adviser_id, {user}

Ten en cuenta

  • Cada id vale solo para su tipo: el id de 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.

Esto es lo que se copia para tu IA

Cargando…