Guía: llamadas y SMS

English version: Guide: calls and SMS.

Las llamadas y los textos salen por un solo camino con puerta: el mismo motor de cumplimiento, venga la petición de una campaña, del panel o de tu llamada a la API. No existe un endpoint de envío en bruto. Las formas de abajo son la autoridad de la Referencia de la API; esta página es el recorrido.

Llamadas

Objetivo	Endpoint
Marcar un número tecleado	POST /v1/dial/manual
Ver el siguiente lead marcable sin marcar	GET /v1/campaigns/{id}/next-lead
Pasar en seco los leads de una campaña por las puertas	GET /v1/campaigns/{id}/compliance-preflight
Retener, silenciar, transferir, colgar una llamada en vivo	POST /v1/calls/{call_id}/hold · …/mute · …/transfer · …/hangup

Marcar un número tecleado

curl -s -X POST $API/v1/dial/manual \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"number": "+13125551001", "agent_id": "<agent uuid>"}'

Una clave dd_ real debe indicar agent_id (400 si falta). El número se resuelve contra los teléfonos de tus propias cuentas; la llamada se hace sólo cuando coincide con exactamente una cuenta marcable, por el originador con puerta (consentimiento, no llamar, la ventana horaria local del destino, frecuencia Reg F, reglas por estado). Resultados: 200 dialing, 200 blocked con el reason de la puerta, o 422 cerrado por defecto con invalid_number, no_account, ambiguous_account, no_campaign o number_quarantined.

Un rechazo de una puerta es una respuesta correcta, no un error que reintentar: es la evidencia de que la llamada no se hizo. Ver Errores y cumplimiento.

SMS

curl -s -X POST $API/v1/sms/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "+13125551001", "body": "Your balance is due. Reply STOP to opt out.", "client_ref": "inv-1001"}'

• client_ref es tu clave de idempotencia. Un reintento con el mismo client_ref responde 202 con duplicate: true y no se vuelve a contactar al proveedor.
• El cuerpo se comprueba antes que nada, con cero llamadas al proveedor y cero filas en el libro si se rechaza: sin aviso de baja → 422 sms_optout_notice_missing; un término prohibido por los operadores → 422 sms_content_prohibited. Reescribir es la única salida.
• El remitente debe ser un número activo de tu cuenta (422 sms_from_invalid / 422 sms_from_not_owned), y un remitente local de EE. UU. (10DLC) necesita una campaña aprobada (422 sms_10dlc_campaign_required): ver la guía de números.
• Sin proveedor configurado → 422 sms_provider_unconfigured. Una cuenta prepago sin tarifa de venta para la región → 422 no_rate.

Más sobre proveedores, plantillas y respuestas: Mensajería SMS.

Probar ambos sin operador

Con una clave dd_test_, las mismas dos peticiones (POST /v1/dial/manual con number, POST /v1/sms/messages con to y body) responden un resultado simulado que elige el destino, y no llegan a ningún operador ni proveedor. Los cuatro números de prueba y lo que devuelve cada uno están en límites y números de prueba; los registros se leen en GET /v1/sandbox/records. El recorrido de punta a punta es el inicio rápido alojado.

Leer resultados

Necesidad	Dónde
La fila durable del CDR con su instantánea de cumplimiento congelada	GET /v1/call_attempts
Qué rechazaron las puertas	GET /v1/stats/blocked
Una llamada terminó, empujada a ti	webhook call.ended: ver Webhooks de salida
Una respuesta entrante o una baja	webhooks sms.received / sms.optout
Cualquier code de error	el índice de errores