--- title: "Campañas, plantillas y novedades" description: "Campañas de llamadas que llegan a una lista de personas, las plantillas de WhatsApp que abren conversaciones y las novedades que les cuentan a todos los agentes lo que pasa durante un tiempo." --- > Documentation Index > Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt > Use this file to discover all available pages before exploring further. # Campañas, plantillas y novedades 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`](/api/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. ```bash 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`](/api/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](/developers/raiz/contacts/#reglas-de-no-contactar) prohíbe el número. Las llamadas de la campaña también están en [`raiz.conversations.list`](/api/raiz/conversations/list/) con `campaignId`. [`raiz.campaigns.update`](/api/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`](/api/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`](/api/raiz/templates/create/) envía una plantilla a revisión de WhatsApp: ```json { "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](/developers/raiz/contacts/#perfiles-de-contacto) de WhatsApp, que abre cada conversación con una, y para el [aviso fuera de horario](/developers/raiz/channels/#horario-de-atención-en-whatsapp) 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`](/api/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: ```json { "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`](/api/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`](/api/raiz/bulletins/update/) cambia una; para terminarla ahora, pon `endsAt` en el instante actual (una programada, en cambio, se elimina). [`raiz.bulletins.delete`](/api/raiz/bulletins/delete/) elimina una que fue un error, y el [historial de cambios](/developers/raiz/data/#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. Source: https://docs.getarbol.com/developers/raiz/campaigns/index.mdx