Inicia una conversación saliente con un agente

Usa las operaciones de conversaciones salientes cuando un contacto existente deba recibir una plantilla aprobada de WhatsApp y continuar con un agente de IA. Para el flujo general, consulta Crear una conversación.

Elige la operación

Objetivo	Operación	Cómo se elige el agente
Iniciar con un LeadScout o Service Agent específico	`POST /bridge/api/v1/workspaces/{workspaceId}/agents/{agentId}/outbound`	Proporcionas el ID de agente obtenido de `GET /agents`.
Iniciar con un LeadScout seleccionado mediante las líneas elegibles del espacio de trabajo	`POST /bridge/api/v1/workspaces/{workspaceId}/leadscout/outbound`	Bridge determina el agente de prospección de la línea.

Ambas usan el host de la API REST https://api-connect-us.bridge.new y una x-api-key desde el servidor. Sus esquemas de solicitud son distintos. Lee la referencia de conversaciones salientes de agentes o la referencia de LeadScout según la operación que uses.

Antes de enviar

Consulta el contacto o créalo si no existe. Estas operaciones exigen que el contacto ya exista en el espacio de trabajo; no necesitas crear antes una conversación o un mensaje independiente.
Lista los agentes. Elige uno disponible y lee su lines[].providerChannelId. El ID de un agente de IA no es el de un usuario humano de Bridge.
Elige una plantilla aprobada. Consulta sus variables, proporciona los valores que debe aportar quien hace la solicitud y comprueba que esté aprobada para la línea de destino. Para este requisito solo necesitas el paso de consulta; no ejecutes el paso de creación de conversación de esa guía antes de una operación de conversación saliente.
Confirma que tu negocio tenga la autorización necesaria. Si envías consent.status: "GRANTED", incluye capturedAt: así registras tu declaración de consentimiento.

En la operación de agentes, contact.providerChannelId debe pertenecer al agente elegido si lo envías. Es una preferencia: se puede seleccionar otra línea elegible de ese agente. En LeadScout se respeta la línea explícita. Identificadores y sus fuentes explica qué valores usar.

Envía una solicitud mínima de agente

Reemplaza todos los valores de ejemplo. Este caso asume que la plantilla elegida no tiene variables obligatorias pendientes que solo puedas proporcionar tú. Define forceSend deliberadamente; el ejemplo mantiene explícito el comportamiento predeterminado.

curl --fail-with-body --request POST \
  "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/outbound" \
  --header "x-api-key: $BRIDGE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "contact": {
      "identifier": "f0000001-0000-4000-8000-000000000001",
      "identifierType": "ID",
      "messageProviderType": "WHATSAPP"
    },
    "template": {
      "id": "f0000040-0000-4000-8000-000000000040"
    },
    "forceSend": false
  }'

Una solicitud exitosa devuelve 201. Conserva conversation.id e interpreta estos campos de respuesta:

Campo	Significado
`alreadyInitiated: true`	Se reutilizó una conversación activa existente. La solicitud exitosa igualmente agrega su nueva plantilla y sus mensajes de seguimiento.
`recovered: true`	Se recuperó una conversación liberada y recuperable, conservando su ID. Se reemplazan su contexto saliente anterior y su `agentContext`.
`additionalMessagesPersisted`	Cantidad de mensajes de seguimiento almacenados. No es una confirmación de entrega.
`templateSent`	Resumen de la plantilla inicial almacenada para enviarla. El nombre del campo no demuestra que el destinatario la haya recibido.

En una creación nueva, ni reutilización ni recuperación se establecen en true. Puede haber recuperación con forceSend: false. Los mensajes adicionales se guardan en el orden de la solicitud: no asumas que esperan la respuesta del contacto. El flujo compartido almacena seguimientos de texto y no adjunta sus mediaIds. Usa la opción documentada template.media para medios en la plantilla inicial o el flujo de adjuntos de mensajes para un mensaje separado.

Qué hace forceSend

La disponibilidad se evalúa para la conversación de este contacto en cada línea. Que una línea esté ocupada en este contexto no significa que la línea corporativa de WhatsApp esté reservada globalmente para un solo contacto. Las reglas siguientes siguen sujetas a la disponibilidad del agente y a las validaciones de plantilla, consentimiento y sesión. En pantallas estrechas, desplázate horizontalmente para comparar las cuatro opciones. Si usas teclado, puedes enfocar esta comparación y recorrerla con las flechas.

Situación	LeadScout: false	LeadScout: true	Agentes: false	Agentes: true
La línea elegida está libre	Crea	Crea	Crea	Crea
La línea elegida contiene una conversación liberada marcada como recuperable	Recupera el mismo ID	Recupera el mismo ID	Recupera el mismo ID	Recupera el mismo ID
La selección automática solo encuentra conversaciones activas ocupadas	`409 …0008`	Reutiliza la primera conversación ocupada elegible	`409 …0008`	Prefiere una controlada por el agente solicitado y aplica la comprobación de controlador indicada abajo
La línea explícita está ocupada	`409 …0007`	Reutiliza esa conversación	Busca otras líneas libres o recuperables del agente; si no hay, `409 …0008`	Busca otras líneas libres o recuperables; si no hay, prefiere una ocupada que controle el agente
La conversación ocupada elegida está controlada por una persona u otro agente	No reutiliza conversaciones activas	La ruta heredada permite reutilizarla, sujeto a otras comprobaciones; esto no promete por sí solo transferir su control	No reutiliza conversaciones activas	`409 BRIDGE_AI_AGENT_OUTBOUND_0006`; este rechazo no escribe nada
Solo hay conversaciones bloqueadas o liberadas no recuperables	`409 …0008`	`409 …0008`	`409 …0008`	`409 …0008`

En la tabla, …0007 es BRIDGE_AI_LEADSCOUT_0007 y …0008 es BRIDGE_AI_LEADSCOUT_0008. Una conversación liberada solo se puede recuperar si lo permite su indicador de recuperación almacenado; forceSend no la convierte en recuperable. En ambas rutas, una sesión de LeadScout abierta y sin vencer bloquea una nueva solicitud de conversación saliente con 409 BRIDGE_AI_LEADSCOUT_0017. Si no se puede finalizar una sesión vencida, se devuelve 409 BRIDGE_AI_LEADSCOUT_0018. Un Service Agent puede continuar su sesión de servicio abierta y vigente; una sesión vencida se cierra antes de abrir otra.

forceSend no es una clave de idempotencia. Repetir una solicitud exitosa puede agregar otra plantilla y más mensajes. No omite conversaciones bloqueadas, comprobaciones de sesión, reglas de aprobación ni validaciones. Si se agota el tiempo de espera, el resultado queda incierto: inspecciona la conversación antes de decidir si vuelves a enviar la solicitud.

Maneja conflictos y efectos parciales

Resultado	Qué hacer
`BRIDGE_AI_LEADSCOUT_0007` / `0008`	Revisa la conversación existente del contacto y sus líneas elegibles. Decide si corresponde reutilizarla antes de habilitar `forceSend`.
`BRIDGE_AI_AGENT_OUTBOUND_0006`	Revisa `extra.conversationId` y quién controla esa conversación. Coordina su control antes de liberarla deliberadamente. No interrumpas automáticamente una conversación humana.
`BRIDGE_AI_LEADSCOUT_0017` / `0018`	Resuelve la sesión existente o contacta a soporte. Cambiar `forceSend` a true no corrige el problema de sesión.
`BRIDGE_AI_LEADSCOUT_0019` / `0020` / `0021`	Usa la consulta de variables para corregir valores faltantes, superpuestos o claves desconocidas.
`400 BRIDGE_AI_LEADSCOUT_0016` por un `mediaId` de plantilla desconocido en la operación de agentes	La conversación puede haberse creado o recuperado antes del error. Revísala antes de reintentar.

Liberar una conversación es una operación independiente con efectos de negocio. Un 204 no tiene cuerpo de respuesta. Libera una conversación solo cuando realmente quieras terminarla.

Solicita una transferencia de LeadScout a una persona

Para una conversación de LeadScout, obtén el ID o correo del usuario humano de Bridge y llama al endpoint de transferencia manual. Esta operación es específica de LeadScout: no asumas que aplica a un Service Agent.

curl --fail-with-body --request POST \
  "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/$WORKSPACE_ID/leadscout/conversations/$CONVERSATION_ID/handoff" \
  --header "x-api-key: $BRIDGE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "assignees": [
      {"identifier": "f0000002-0000-4000-8000-000000000002", "identifierType": "ID"}
    ]
  }'

Un 202 confirma la aceptación de la solicitud. Conserva trackingId y conversationId; la aceptación no demuestra que haya terminado la asignación ni que una persona haya leído o respondido la conversación. La referencia no publica un endpoint de seguimiento de transferencias: no construyas uno a partir de trackingId. Continúa con el manejo de errores y la recepción de webhooks para conectar este flujo a tu sistema.

Empieza aquí

Crea tu integración

Referencia

Elige la operación

Antes de enviar

Envía una solicitud mínima de agente

Qué hace forceSend

Maneja conflictos y efectos parciales

Solicita una transferencia de LeadScout a una persona