API Outbound

Con la API Outbound inicias una llamada de tu agente con una sola solicitud HTTP. Pasas el número de destino, el número de origen y los datos de contexto, bhomy pone en marcha al agente y este lleva la conversación con los valores de tu contexto.

De un vistazo

Crear una clave API

La solicitud

El agente se determina por el número de origen. No indicas ningún ID de agente.

curl -X POST https://app.bhomy.ai/api/v1/outbound \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9c2b1e-7a3d-4c55-9a0e-2d6f8b1c3e77" \
  -d '{
    "toNumber": "+491701234567",
    "fromNumber": "+494012345678",
    "context": {
      "customer_name": "Anna Berger",
      "appointment": "15 de enero"
    }
  }'

Se permiten espacios, guiones y paréntesis en los números, así como un (0) después del prefijo del país. La API rechaza un número sin signo más en lugar de adivinar un país.

Usar el contexto en la conversación

Cada campo de context está disponible como variable. En el prompt o en el saludo lo escribes entre dobles llaves:

Hola, {{customer_name}}, le habla el asistente de la empresa Sommer. Le llamo por su
cita del {{appointment}}.

Si falta un campo en context, bhomy lo elimina del texto. Mantén los valores planos y tal como se dicen.

La respuesta

Si todo va bien, la API responde con 202. Después el agente marca. El resultado de la conversación aparece más tarde en el historial de llamadas y se envía a tus automatizaciones.

{
  "success": true,
  "callId": "call_8f2a1c",
  "roomName": "outbound_call_8f2a1c",
  "status": "queued",
  "dispatchId": "AD_x7Kp2",
  "message": "Calling +491701234567"
}

En caso de error, error contiene un código fijo al que tu integración puede reaccionar, y message una explicación. Todos los códigos con su solución: Códigos de error de la API.

Idempotencia: cada llamada exactamente una vez

Las herramientas de automatización repiten las solicitudes cuando no llega una respuesta. Para que nadie reciba dos llamadas, envías un header Idempotency-Key con un valor nuevo por llamada, por ejemplo un UUID o el ID de la fila de tu hoja de cálculo.

Sin el header, cada solicitud inicia una llamada nueva.

Límites

Con 429, espera los segundos indicados en Retry-After antes de volver a intentarlo.

Ejemplos para herramientas de automatización

Recibir los resultados

La API solo informa de si se aceptó el encargo. Cómo terminó la conversación lo recibes después de la llamada a través del Ticket CRM en la pestaña Herramientas › Automatización: con callId, resumen, transcripción y datos recogidos. Con el callId asignas el resultado a tu encargo.