API de WhatsApp y CRM
POST/campaigns

Crear campaña

Crea una nueva campaña de mensajes que se entregará a una lista de destinatarios a través de un número de WhatsApp específico.

API de WhatsApp y CRM
Necesitas una clave de API. Pídela a nuestro equipo de soporte o créala desde la plataforma.
POST https://api.getincloud.ai/v1/campaigns

Crea una nueva campaña de mensajes que se entregará a una lista de destinatarios a través de un número de WhatsApp específico.

El campo name es obligatorio e identifica la nueva campaña con un alias.

El campo device es obligatorio y debe ser el ID de un dispositivo de WhatsApp válido y conectado en tu cuenta.

Ten en cuenta que las campañas no se activan automáticamente al crearse, sino que se crean en modo draft.

Una vez creada la campaña, puedes agregar los contactos destinatarios, un mensaje para enviar y, finalmente, activarla actualizando el estado de la campaña.

Las campañas solo pueden entregarse a través de un número de WhatsApp (dispositivo) específico. Para enviarla a través de varios números de WhatsApp, puedes repetir o clonar la campaña para cada número de WhatsApp de destino conectado en tu cuenta.

Las campañas pueden programarse para entregarse en una fecha y hora específicas, o inmediatamente después de su activación.

Nueva función: opcionalmente puedes habilitar la función nativa de cancelación de suscripción, que permite a los destinatarios responder con una palabra predefinida como stop para darse de baja automáticamente de cualquier campaña de mensajes futura. Esta función está incluida en todos los planes actuales de Platform: los números con un plan Gateway o heredado deben actualizarse para usarla.

Se aplican limitaciones: solo se puede entregar una campaña por día por número de WhatsApp. Según tu plan de suscripción, puedes crear de 5 a 30 campañas al mes.


Prueba este endpoint en el probador de API en vivo

>¿Necesitas ayuda? Explora todos los tutoriales, más de 100 ejemplos de casos de uso y prueba la API en el probador en vivo con ejemplos de código listos para usar en más de 15 lenguajes de programación, incluidos JavaScript/Node.js, PHP, Python, C#, Java, Ruby, Swift, Kotlin, Powershell, cURL y más.

Autenticación

Envía tu API key en el encabezado Token en cada petición.

Cuerpo de la petición

CampoTipoObligatorioDescripción
namestringSíNombre de la campaña. Obligatorio. minLength: 1 · maxLength: 50
devicestringSíID del dispositivo de WhatsApp de destino que se usará para la entrega de los mensajes de la campaña minLength: 24 · maxLength: 24 · pattern: ^[0-9a-fA-F]{24}$
messagestringNoOpcional. Mensaje general que se enviará en la campaña. Si no se especifica, se usará en su lugar el mensaje de la campaña. El mensaje puede usar [variables de plantilla](/help/templates) y la [sintaxis de texto enriquecido de WhatsApp](/help/text-format) para dar formato al mensaje. minLength: 2 · maxLength: 10000
templateobjectNoMensaje de plantilla preaprobada de WABA que se enviará. Obligatorio si los campos message y file están vacíos. Solo disponible en números habilitados para WABA.
template.namestringSíNombre de la plantilla (solo minúsculas, caracteres alfanuméricos y guiones bajos) maxLength: 512 · pattern: ^[a-z0-9_]+$
template.languagestringNoCódigo de idioma de la plantilla. Ejemplo: en_US, de_DE, es_MX, etc. minLength: 2 · maxLength: 5
filestringNoOpcional. ID del archivo de imagen, video o documento (image/*, video/mp4 o application/pdf) que se enviará en cada mensaje de esta campaña. El archivo debe haberse subido previamente mediante la [API de carga de archivos](#tag/Files/operation/uploadFile). Establécelo en null para eliminar el archivo existente. minLength: 24 · maxLength: 24 · pattern: ^[0-9a-fA-F]{24}$
filenamestringNoOpcional. Nombre de archivo que se usará cuando el usuario descargue el archivo. Solo aplicable a números de la API de WABA. maxLength: 50
activatebooleanNoOpcional. Activa la campaña después de actualizarla. Si no se especifica, la campaña permanecerá en modo borrador.\nImportante: solo se pueden activar campañas con una fecha configurada y al menos un contacto; de lo contrario, se devolverá un error. default: False
settingsobjectNoConfiguración de la campaña, como fecha y hora de entrega, velocidad de entrega de mensajes, zona horaria y horarios de entrega permitidos
settings.speednumberNoVelocidad de entrega de los mensajes de la campaña por minuto. Para reducir el riesgo de ser bloqueado por envío de spam o mensajes masivos, usa 1 mensaje por minuto o más. Alternativamente, para una entrega más rápida usa: 0.5 = 2 mensajes por minuto, 0.3 = 3 mensajes por minuto, 0.2 = 4 mensajes por minuto enum: [0.025, 0.0286, 0.0333, 0.04, 0.05, 0.0667, 0.1, 0.15, 0.2, 0.3, 0.5, 1, 1.25, 1.5, 1.75, 2, 2.5, 3, 4, 5] · minimum: 0 · maximum: 5 · format: float
settings.datestringNoFecha y hora de entrega de la campaña en formato ISO 8601 YYYY-MM-DDTHH:MM:SSZ. Ejemplo: 2024-01-15T14:00:00Z. La hora se basa por defecto en la configuración de zona horaria de tu cuenta, pero puedes reemplazarla especificando un campo timezone en la configuración (ver abajo) format: date-time
settings.expirationstringNoOpcional. Tiempo de expiración de la campaña. Por defecto es 3 días = 3d. Si los mensajes de la campaña no se procesan por completo en el tiempo indicado, la campaña se detendrá automáticamente y se marcará como incomplete. Ejemplo: 24h enum: ['4h', '8h', '12h', '24h', '2d', '3d', '4d', '5d', '6d', '7d', '15d']
settings.timezonestringNoOpcional. Zona horaria que se usará. Si no se especifica, se usará la zona horaria predeterminada de tu cuenta. Ejemplo: America/New_York. Consulta aquí la lista de valores de zona horaria permitidos minLength: 1 · maxLength: 100
contactsarray<object>No
actionsarray<object>NoLista opcional de acciones que se ejecutarán después de la entrega del mensaje. El alcance de las acciones se limita al chat o contacto que recibe el mensaje. Si la entrega del mensaje falla, las acciones se ignorarán. Nota: esta función solo es aplicable a dispositivos con soporte de chat multiagente. ### Acciones admitidas * Action: chat:assign * Description: Asigna el chat a un agente. * Params: - agent: string (opcional) - Obligatorio si department no está definido. ID del agente al que se asignará el chat después de la entrega del mensaje. Puedes obtener los ID de los agentes [desde aquí](#operation/getDeviceAgents) - department: string (opcional) - Obligatorio si agent no está definido. ID del departamento al que se asignará el chat después de la entrega del mensaje. Puede usarse junto con el campo agent para asignar un chat tanto a un agente como a un departamento. Puedes obtener el ID del departamento [desde aquí](#operation/getDepartments) - assigner: string (opcional) - Opcional. ID del agente que asigna el chat al otro agente ---- * Action: chat:unassign * Description: Desasigna el chat del agente actual * Params: - assigner: string (opcional) - ID del agente que asigna el chat al otro agente. Puedes obtener los ID de los agentes [desde aquí](#operation/getDeviceAgents) ---- * Action: chat:resolve * Description: Resuelve el chat si aún no está resuelto. No se puede usar junto con la acción chat:unresolve. * Params: no params accepted ---- * Action: chat:unresolve * Description: Marca el chat como no resuelto si ya estaba resuelto. No se puede usar junto con la acción chat:resolve. * Params: no params accepted ---- * Action: chat:read * Description: Marca el chat internamente como leído en la interfaz web del chat después de entregar el mensaje. No se puede usar junto con la acción chat:resolve. * Params: no params accepted ---- * Action: chat:unread * Description: Marca el chat internamente como no leído en la interfaz web del chat después de entregar el mensaje. No se puede usar junto con la acción chat:resolve. * Params: no params accepted ---- * Action: labels:add * Description: Agrega etiquetas al chat después de entregar el mensaje * Params: - labels: array (opcional) - Etiquetas que se agregarán al chat conservando las existentes. Puedes obtener la lista de etiquetas existentes [consultando este endpoint](#operation/getLabels) ---- * Action: labels:remove * Description: Elimina etiquetas del chat, cuando ya están presentes, después de entregar el mensaje * Params: - labels: array (opcional) - Etiquetas que se eliminarán del chat. Puedes obtener la lista de etiquetas existentes [consultando este endpoint](#operation/getLabels) ---- * Action: labels:set * Description: Establece y reemplaza las etiquetas del chat después de entregar el mensaje * Params: - labels: array (opcional) - Etiquetas que se establecerán y reemplazarán en el chat. Puedes obtener la lista de etiquetas existentes [consultando este endpoint](#operation/getLabels) ---- * Action: metadata:set * Description: Establece y reemplaza las entradas de metadatos clave-valor en la entidad de contacto del chat de destino después de entregar el mensaje * Params: - metadata: array (opcional) - Entradas de metadatos con las propiedades key y value que se establecerán y reemplazarán en el contacto del chat ---- * Action: metadata:add * Description: Agrega entradas de metadatos clave-valor en la entidad de contacto del chat de destino, o reemplaza las existentes según el campo key, después de entregar el mensaje * Params: - metadata: array (opcional) - Entradas de metadatos con las propiedades key y value que se añadirán al contacto del chat ---- * Action: metadata:remove * Description: Elimina entradas de metadatos existentes según el campo key en la entidad de contacto del chat de destino después de entregar el mensaje * Params: - keys: array (opcional) - Entradas de metadatos que se eliminarán por key en el contacto del chat
unsubscribeobjectNoOpcionalmente permite a los usuarios cancelar su suscripción a los mensajes de la campaña. Si está habilitado, los usuarios pueden responder con una palabra predefinida para dejar de recibir mensajes de futuras campañas.
unsubscribe.activebooleanNoEstablécelo en true para habilitar la función automática de baja de campañas. Si está habilitada, los usuarios pueden responder con una palabra predefinida para dejar de recibir mensajes de la campaña. Nota: esta función está incluida en todos los planes actuales de Platform. default: False
unsubscribe.wordstringNoPalabra de cancelación de suscripción para dejar de recibir mensajes de la campaña. Si no se especifica, se usará la palabra predeterminada stop. minLength: 2 · maxLength: 30
unsubscribe.messagestringNoMensaje de cancelación de suscripción que se añadirá al final del mensaje de la campaña para informar a los destinatarios cómo darse de baja de futuras campañas. El mensaje debe contener el valor especificado en el campo word o stop como parte del texto del mensaje. Obligatorio cuando active es true. Ejemplo de mensaje: Reply *stop* to unsubscribe. Nota: el mensaje se ignora al enviar plantillas de WABA debido a las restricciones de contenido preaprobado; en su lugar, puedes agregar el mensaje de cancelación de suscripción en el pie de página de la plantilla. minLength: 10 · maxLength: 500
unsubscribe.actionsarray<object>NoLista opcional de acciones que se ejecutarán después de que el usuario responda para cancelar su suscripción. Las acciones solo se ejecutarán en el chat específico que activó la función de cancelación de suscripción al responder con la palabra definida, por ejemplo: stop. Nota: esta función solo es aplicable si la campaña tiene habilitada la función de cancelación de suscripción, que está incluida en todos los planes actuales de Platform. ### Acciones admitidas * Action: message:send * Description: Envía un mensaje automático para confirmar que el usuario se ha dado de baja correctamente. Esta acción está limitada a campañas con la función de baja habilitada. * Params: - message: string (opcional) - Texto del mensaje que se enviará como acción automática de respuesta ---- * Action: chat:assign * Description: Asigna el chat a un agente. * Params: - agent: string (opcional) - Obligatorio si department no está definido. ID del agente al que se asignará el chat después de la entrega del mensaje. Puedes obtener los ID de los agentes [desde aquí](#operation/getDeviceAgents) - department: string (opcional) - Obligatorio si agent no está definido. ID del departamento al que se asignará el chat después de la entrega del mensaje. Puede usarse junto con el campo agent para asignar un chat tanto a un agente como a un departamento. Puedes obtener el ID del departamento [desde aquí](#operation/getDepartments) - assigner: string (opcional) - Opcional. ID del agente que asigna el chat al otro agente ---- * Action: chat:unassign * Description: Desasigna el chat del agente actual * Params: - assigner: string (opcional) - ID del agente que asigna el chat al otro agente. Puedes obtener los ID de los agentes [desde aquí](#operation/getDeviceAgents) ---- * Action: chat:resolve * Description: Resuelve el chat si aún no está resuelto. No se puede usar junto con la acción chat:unresolve. * Params: no params accepted ---- * Action: chat:unresolve * Description: Marca el chat como no resuelto si ya estaba resuelto. No se puede usar junto con la acción chat:resolve. * Params: no params accepted ---- * Action: chat:read * Description: Marca el chat internamente como leído en la interfaz web del chat después de entregar el mensaje. No se puede usar junto con la acción chat:resolve. * Params: no params accepted ---- * Action: chat:unread * Description: Marca el chat internamente como no leído en la interfaz web del chat después de entregar el mensaje. No se puede usar junto con la acción chat:resolve. * Params: no params accepted ---- * Action: labels:add * Description: Agrega etiquetas al chat después de entregar el mensaje * Params: - labels: array (opcional) - Etiquetas que se agregarán al chat conservando las existentes. Puedes obtener la lista de etiquetas existentes [consultando este endpoint](#operation/getLabels) ---- * Action: labels:remove * Description: Elimina etiquetas del chat, cuando ya están presentes, después de entregar el mensaje * Params: - labels: array (opcional) - Etiquetas que se eliminarán del chat. Puedes obtener la lista de etiquetas existentes [consultando este endpoint](#operation/getLabels) ---- * Action: labels:set * Description: Establece y reemplaza las etiquetas del chat después de entregar el mensaje * Params: - labels: array (opcional) - Etiquetas que se establecerán y reemplazarán en el chat. Puedes obtener la lista de etiquetas existentes [consultando este endpoint](#operation/getLabels) ---- * Action: metadata:set * Description: Establece y reemplaza las entradas de metadatos clave-valor en la entidad de contacto del chat de destino después de entregar el mensaje * Params: - metadata: array (opcional) - Entradas de metadatos con las propiedades key y value que se establecerán y reemplazarán en el contacto del chat ---- * Action: metadata:add * Description: Agrega entradas de metadatos clave-valor en la entidad de contacto del chat de destino, o reemplaza las existentes según el campo key, después de entregar el mensaje * Params: - metadata: array (opcional) - Entradas de metadatos con las propiedades key y value que se añadirán al contacto del chat ---- * Action: metadata:remove * Description: Elimina entradas de metadatos existentes según el campo key en la entidad de contacto del chat de destino después de entregar el mensaje * Params: - keys: array (opcional) - Entradas de metadatos que se eliminarán por key en el contacto del chat

Respuestas

CódigoDescripción
200Nueva campaña creada
400Datos de consulta o cuerpo de la solicitud no válidos
401No autorizado: token de API no válido o ausente
403Faltan los permisos necesarios
404Recurso no encontrado
409Conflicto
429Demasiadas solicitudes: inténtalo de nuevo más tarde
500Error inesperado
501No implementado
503Servicio no disponible temporalmente: inténtalo de nuevo más tarde
// This code example requires you to have installed curl package
// Installation instructions here: https://curl.haxx.se/download.html

// Create new campaign
curl --request POST \
  --url https://api.getincloud.ai/v1/campaigns \
  --header 'Content-Type: application/json' \
  --header 'Token: <api token goes here>' \
  --data '{"name":"Campaign test","device":"{{device.id}}>","message":"Dear {{ name }}, this is a sample message campaign with template variables","activate":false,"settings":{"date":"2026-10-11T14:52:46.988Z","speed":1}}'


// Create new campaign with contacts and different message per recipient
curl --request POST \
  --url https://api.getincloud.ai/v1/campaigns \
  --header 'Content-Type: application/json' \
  --header 'Token: <api token goes here>' \
  --data '{"name":"Campaign with contacts","device":"{{device.id}}>","activate":true,"contacts":[{"phone":"+1234567890","name":"John","message":"Dear {{ name }}, your package is in delivery and will arrive soon to {{ address }}","variables":[{"key":"address","value":"123 Main St, New York, NY 10030"}]},{"phone":"+1234567890","name":"Mary","message":"Dear {{ name }}, package delivery failed, please contact us to reschedule the delivery at {{ support_phone }}","variables":[{"key":"support_phone","value":"+19402930131"}]},{"phone":"+1234567890","name":"Elisabeth","message":"Dear {{ name }}, your order {{ order }} has shipped, thank you for your purchase! Rate your experience: {{ rate_url }}","variables":[{"key":"order","value":"9582311"},{"key":"rate_url","value":"https://company.com/rate?order=9582311"}]}],"settings":{"date":"2026-10-11T14:52:46.988Z","speed":1}}'


// Create new campaign with unsubscribe feature
curl --request POST \
  --url https://api.getincloud.ai/v1/campaigns \
  --header 'Content-Type: application/json' \
  --header 'Token: <api token goes here>' \
  --data '{"name":"Campaign with contacts","device":"{{device.id}}>","activate":true,"unsubscribe":{"active":true,"word":"stop","message":"Reply *{{word}}** to unsubscribe","actions":[{"action":"message:send","params":{"message":"You’ve successfully unsubscribed and won’t receive any more communications."}},{"action":"metadata:add","params":{"metadata":[{"key":"unsubscribed","value":"true"}]}}]},"contacts":[{"phone":"+1234567890","name":"John","message":"Dear {{ name }}, your package is in delivery and will arrive soon to {{ address }}","variables":[{"key":"address","value":"123 Main St, New York, NY 10030"}]},{"phone":"+1234567890","name":"Mary","message":"Dear {{ name }}, package delivery failed, please contact us to reschedule the delivery at {{ support_phone }}","variables":[{"key":"support_phone","value":"+19402930131"}]},{"phone":"+1234567890","name":"Elisabeth","message":"Dear {{ name }}, your order {{ order }} has shipped, thank you for your purchase! Rate your experience: {{ rate_url }}","variables":[{"key":"order","value":"9582311"},{"key":"rate_url","value":"https://company.com/rate?order=9582311"}]}],"settings":{"date":"2026-10-11T14:52:46.988Z","speed":1}}'
AnteriorActualizar contactos de una campañaSiguienteEliminar campaña
¿Te sirvió esta página?