Raíz puede tomar la iniciativa además de responder. Una campaña hace que un agente de voz llame a una lista de personas dentro del horario que permitas, y puede volver a llamar a quienes no contestaron. En WhatsApp, una conversación que inicia tu organización debe abrirse con una plantilla de mensaje que WhatsApp haya aprobado. Y cuando algo cambia por un tiempo, como un día cerrado o un servicio que no está disponible, una novedad les avisa a tus agentes sin tocar sus instrucciones.
Campañas de llamadas
raiz.campaigns.create prepara una campaña para un agente de voz, con hasta 10.000 recipients. Crearla no llama a nadie: la campaña queda en queued hasta que se inicia. La llamada no es idempotente.
curl https://api.getarbol.com/v1/raiz/campaigns \
--request POST \
--header "Authorization: Bearer $ARBOL_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Recordatorios de citas, noviembre",
"agentId": "agt_01jd8xq4r5s6t7v8w9x0y1z2a3",
"instructions": "Recuérdale a {{contact_given_name}} su cita del {{appointment_date}} y pregúntale si va a asistir.",
"contactHours": [{ "days": ["MO", "TU", "WE", "TH", "FR"], "from": "08:00", "to": "18:00" }],
"timeZone": "America/Bogota",
"maxAttempts": 3,
"retryAfterMinutes": 120,
"recipients": [
{ "address": "+12025550143", "variables": { "appointment_date": "12 de noviembre" } }
]
}'| Campo | Qué hace |
|---|---|
agentId |
El agente de voz que llama. Uno que todavía no puede hacer llamadas responde 409 VOICE_AGENT_NOT_READY: debe estar activo, tener instrucciones y estar publicado para llamadas. |
recipients |
Cada uno es una address telefónica en E.164, única en la campaña, con un contactId, unas variables y un firstMessage y unas instructions para esa llamada, todos opcionales. |
firstMessage, instructions |
Lo primero que dice el agente en cada llamada, y de qué tratan estas llamadas, que se suma a las instrucciones del agente. |
contactHours, timeZone |
Cuándo pueden empezar las llamadas, en la zona horaria de la campaña, que por defecto es la de la organización. Vacío: a cualquier hora. |
scheduledStartAt, scheduledEndAt |
Ninguna llamada empieza antes ni después de estos instantes. |
maxAttempts, retryAfterMinutes, retryOn |
Las llamadas por destinatario, reintentos incluidos (de 1 a 10, 1 por defecto); la espera antes de un reintento (60 minutos por defecto); y qué resultados dan lugar a uno: no_answer (el valor por defecto) y failure. |
channelId |
La línea de voz desde la que salen las llamadas. Por defecto, la línea saliente del propio agente. |
Los textos del agente y de la campaña pueden usar variables {{name}}, que se llenan con las variables de cada destinatario. Raíz siempre proporciona contact_name, contact_given_name, contact_id, contact_phone, conversation_id y bulletins (las novedades vigentes), y los valores de un destinatario nunca los reemplazan. El contacto de un destinatario es el que este nombra o, si no, el contacto dueño de su número, que se crea cuando no hay ninguno.
Seguir y cambiar una campaña
El status de una campaña es queued (no ha empezado, o su inicio está programado), running (llamando a los destinatarios que corresponden), paused (no empieza ninguna llamada nueva; las que están en curso terminan), completed (no queda nadie por llamar), cancelled o failed. Su progress cuenta sus recipients y cuántos están pending, inProgress, completed o failed, y cuántos succeeded: el análisis de su última llamada la juzgó exitosa.
raiz.campaigns.get con expand=recipients agrega el estado de cada destinatario, sus intentos, su próximo intento y su última llamada, cuyo conversationId lleva a su transcripción. Un destinatario que falló dice por qué en errorCode: NO_ANSWER o CALL_FAILED después de su último intento, o CONTACT_SUPPRESSED cuando una regla de no contactar prohíbe el número. Las llamadas de la campaña también están en raiz.conversations.list con campaignId.
raiz.campaigns.update cambia una campaña; los campos que omites se quedan. "paused": true pausa una campaña iniciada y false la reanuda, con las mismas verificaciones que al iniciarla; en una campaña que nunca empezó, responde 409 INVALID_STATE. Antes del inicio, recipients es la lista completa, emparejada por address; una vez iniciada, solo agrega, así que puedes enviar una lista larga por lotes. El agente solo cambia antes del inicio, y una campaña completada solo acepta un name y una metadata nuevos. Tu organización hace como máximo settings.channels.maxConcurrentOutboundCalls llamadas de campaña a la vez (5 por defecto).
Plantillas de WhatsApp
WhatsApp solo le permite a una empresa iniciar una conversación, o escribirle a alguien que no ha escrito en las últimas 24 horas, con una plantilla de mensaje que haya aprobado. Las plantillas pertenecen a la cuenta de WhatsApp Business de cada número, así que ambas operaciones de plantillas reciben un channelId de WhatsApp.
raiz.templates.list lee en vivo desde WhatsApp las plantillas de un canal, de la más reciente a la más antigua, y las filtra por status: approved, pending o rejected. sendable dice si Raíz puede enviar una: aprobada, con variables solo en el cuerpo y, si tiene un encabezado multimedia, que sea un documento, una imagen o un video. parameterCount es cuántos valores de cuerpo necesita un envío.
raiz.templates.create envía una plantilla a revisión de WhatsApp:
{
"channelId": "chn_01jd8x6b3c4d5e6f7g8h9j0k1m",
"name": "appointment_reminder",
"language": "en_US",
"category": "utility",
"body": {
"text": "Hello {{1}}, this is a reminder of your appointment on {{2}} at Example Clinic.",
"examples": ["Ana", "November 12"]
}
}El name admite letras minúsculas, dígitos y _, y el language, el código de WhatsApp, como es, es_MX o en_US. category es utility para mensajes sobre algo que la persona pidió, como citas, o marketing para promociones. El body tiene hasta 1024 caracteres con variables {{1}}, {{2}} y así sucesivamente, y un valor de examples por variable. Un header (un texto fijo, o un documento, una imagen o un video con un archivo de muestra de hasta 5 MiB), un footer y hasta 10 buttons son opcionales. La plantilla queda en pending hasta que WhatsApp la aprueba o la rechaza, normalmente en minutos; WhatsApp puede cambiar su categoría, y rejectedReason dice por qué se rechazó.
También eliges plantillas aprobadas para un perfil de contacto de WhatsApp, que abre cada conversación con una, y para el aviso fuera de horario de un número.
Novedades
Una novedad (bulletin, en la API) les cuenta a tus agentes algo que pasa durante un tiempo: un servicio que no está disponible, ninguna cita en una sede durante unos días, un día cerrado, una promoción. Los agentes la aplican en las llamadas, en WhatsApp y en el chat web hasta que termina. No se le envía a nadie; los agentes la tienen en cuenta cuando hablan con las personas. Tu equipo puede llamarlas novedades o avisos.
raiz.bulletins.create recibe el text, de hasta 1000 caracteres, escrito como se lo dirías a tus agentes, con lo que deben ofrecer en su lugar. Agrega un agentId para un solo agente, u omítelo para todos los agentes. startsAt es ahora por defecto, y sin endsAt la novedad dura hasta que se elimine. En este ejemplo, Example Clinic trabaja en America/Bogota, así que sus días terminan a las 05:00 UTC:
{
"text": "La sede Norte está cerrada del 24 al 26 de noviembre. Ofrece citas en la sede Sur en su lugar.",
"endsAt": "2026-11-27T05:00:00Z"
}Los agentes aplican una novedad desde su siguiente respuesta o llamada una vez que empieza, y ningún agente la lee antes. Para que los agentes lo sepan con anticipación y no agenden nada en un día cerrado, iníciala ahora y escribe las fechas en el texto, como arriba. El status de una novedad es scheduled, active o ended. Una organización puede tener 30 novedades vigentes o programadas (409 BULLETIN_LIMIT_REACHED), y una que terminaría antes de empezar, o que ya habría terminado, responde 422 BULLETIN_PERIOD_INVALID.
raiz.bulletins.list lista las novedades programadas y activas, o las terminadas con status=ended, por agentId o por texto con q. raiz.bulletins.update cambia una; para terminarla ahora, pon endsAt en el instante actual (una programada, en cambio, se elimina). raiz.bulletins.delete elimina una que fue un error, y el historial de cambios conserva quién la eliminó. Las novedades usan los permisos (scopes) de agentes: raiz:agents:write para publicar, cambiar o eliminar una.