## URL de la API URL utilizada para enviar las solicitudes HTTP: ```url https://portal.bulkgate.com/api/2.0/advanced/promotional ``` > [!NOTE] > Si la solicitud no llega a su destino, repítala en el [servidor de respaldo](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/servidor-de-respaldo/) `backup1.bulkgate.com`. ## Métodos HTTP compatibles - `POST` - `application/json` ```http POST /api/2.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` ## Tabla de parámetros | NOMBRE DEL PARÁMETRO | VALOR | OBLIGATORIO | VALOR PREDETERMINADO | |:------------------|:-----------------------------------------------------|:------------------------------------------:|:------------------------------------------:| | application_id | [Application ID](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/administracion-api/) | **Sí** | - | | application_token | [Application token](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tokens-de-api/) | **Sí** | - | | number | Array de destinatarios - [Valor number](#valor-number) | **Sí** o `admins` o `groups` | - | | groups | Array de números de grupos de la agenda de contactos de BulkGate. [Más información](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-envio-a-grupos/) | **Sí** o `number` o `admins` | - | | admins | Array de números de administradores de BulkGate que reciben notificaciones. [Más información](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-promotional-envio-a-administradores/) | **Sí** o `number` o `groups` | - | | text | Texto del mensaje SMS (máx. 612 caracteres, o 268 caracteres si se activa Unicode), codificación UTF-8 | **Sí**, si `number` se indica mediante el array de números o se utiliza el parámetro `groups` o `admin` | - | | channel | Canales alternativos. Los canales se prueban en cascada, en el orden en que los indique en el objeto: si no conseguimos entregar el mensaje por el primer canal, se utiliza el siguiente de la lista. El SMS **no** se añade automáticamente; si lo quiere como última alternativa, incluya el objeto `sms` en la cascada. Si no se indica ningún canal, el mensaje se envía como SMS. | No | [Objeto SMS](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-sms/) | | country | Indique los números de los destinatarios en formato internacional (con prefijo, p. ej. `420`) o añada el [código de país](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`777777777` + `CZ` = `420777777777`). Consulte el ejemplo de solicitud con país. Si el valor es **`null`**, la información se completará según la zona horaria configurada | No | `null` | | schedule | Programe la fecha y la hora de envío en [unix timestamp,](https://en.wikipedia.org/wiki/Unix_time) o [ISO 8601.](https://en.wikipedia.org/wiki/ISO_8601) Consulte los ejemplos de abajo | No | Ahora | | duplicates_check | Seleccione **`same_text`** para evitar el envío de mensajes duplicados al mismo número de teléfono. Con **`same_number`** desactiva la posibilidad de enviar un mensaje con el mismo texto o con otro distinto al mismo número. Si es **`null`**, no se eliminará ningún duplicado. Los duplicados se eliminan **solo dentro de un mismo lote**, no entre solicitudes distintas. | No | `null` | | tag | Etiqueta del mensaje para que el usuario pueda localizarlo posteriormente. | No | - | ### Valor `number` El valor number puede escribirse de dos maneras: - Array de números de teléfono ```json [ "420777777777", "420888888888", "420999999999" ] ``` - Array asociativo con el esquema `number`, `text` y `variables`, donde el único parámetro obligatorio es `number`. Si `number` no está rellenado, el mensaje se omite. ```json [ {"number": "420777777777", "text": "test1 ", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 ", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ] ``` En la plantilla del parámetro `text` puede añadir variables del array `variables`. ## Canales El objeto `channel` determina por qué canales se envía el mensaje y en qué orden. **El orden de las claves en su solicitud es el orden de la cascada** y el SMS no se añade automáticamente al final; consulte [Cascada de canales](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-cascada-de-canales/). | CLAVE | OBJETO DEL CANAL | |:-------------|:---------------------------------------------------------------| | `sms` | [SMS](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-sms/) | | `viber` | [Viber – promocional](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-viber-promotional/) | | `rcs` | [RCS](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-rcs/) | | `whatsapp` | [WhatsApp](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-whatsapp/) | ## Ejemplos de solicitudes **Ejemplo de solicitud completa:** ```http-json POST /api/2.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ {"number": "420777777777", "text": "test1 ", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 ", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ], "groups": [1, 2], "admins": [1, 4], "text": "RCS: el futuro de la mensajería móvil para empresas", "country": "cz", "schedule": "2018-05-14T18:30:00-01:00", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "message": { "text": "text" } }, "rcs": { "sender": "BulkGate", "expiration": 300, "message": { "text": "text" } }, "viber": { "sender": "Lt. Hagan", "expiration": 100, "button": { "caption": "Ir a BulkGate", "url": "https://www.bulkgate.com/en/blog/rcs-the-future-of-mobile-messaging-for-businesses/" }, "image": "https://www.bulkgate.com/assets/illustrations/rcs-rich-communication-services.jpg", "text": "*RCS: el futuro de la mensajería móvil para empresas*\n\n¿Alguna vez ha deseado enviar en un SMS algo más que texto, como una imagen en alta resolución o un botón interactivo? ¿O quizá le habría gustado recibir una confirmación de lectura para asegurarse de que su mensaje ha llegado? Rich Communication Services (RCS) llega para revolucionar la forma en que se comunican las empresas, mejorar la experiencia de mensajería y superar estas limitaciones." }, "sms": { "sender_id": "gText", "sender_id_value": "Lt-Hagan", "unicode": true, "text": "RCS: el futuro de la mensajería móvil para empresas" } } } ``` **Ejemplo de solicitud que indica los destinatarios mediante un array de números y programa la hora en unix timestamp:** ```http-json POST /api/2.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ "420777777777", "420888888888", "420999999999" ], "text": "Hello, ", "schedule": "1526992636" } ``` ## Respuesta **En caso de éxito:** ```json { "data":{ "total":{ "status":{ "sent":0, "accepted":0, "scheduled":2, "error":0, "blacklisted":0, "invalid_number":1, "invalid_sender":0 } }, "response":[ { "status":"scheduled", "sms_id":"idyrcmdd-0", "part_id":[ "idyrcmdd-0_1", "idyrcmdd-0" ], "number":"420777777777", "channel":"sms" }, { "status":"scheduled", "sms_id":"idyrcmdd-1", "part_id":[ "idyrcmdd-1_1", "idyrcmdd-1" ], "number":"420888888888", "channel":"sms" }, { "status":"invalid_number", "code":400, "error":"Invalid phone number", "detail":null, "number":"420999999999", "channel":"sms" } ] } } ``` Donde: - **part_ID** es el array de ID de las partes del mensaje largo original, que se dividió porque superaba el límite de 160 caracteres de un solo mensaje. Más información [aquí](https://www.bulkgate.com/es/centro-de-ayuda/sms/concatenacion-de-mensajes/). **En caso de error:** ```json { "type": "invalid_phone_number", "code": 400, "error": "Invalid phone number", "detail": null } ``` ```json { "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null } ``` Donde: - **type** y **error** (descripción del error) se encuentran en la [tabla de tipos de error](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tipos-de-error/) - **code** representa el error HTTP - **detail** es información adicional sobre el error Consulte todos los tipos de error de Simple API y Advanced API [aquí](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tipos-de-error/).