SMS promocional – especificación (Advanced API)

URL de la API

URL utilizada para enviar las solicitudes HTTP:

https://portal.bulkgate.com/api/2.0/advanced/promotional

Nota

Si la solicitud no llega a su destino, repítala en el servidor de respaldo backup1.bulkgate.com.

Métodos HTTP compatibles

POST - application/json

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	Sí	-
application_token	Application token	Sí	-
number	Array de destinatarios - 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	Sí o `number` o `admins`	-
admins	Array de números de administradores de BulkGate que reciben notificaciones. Más información	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
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 (`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, o 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

[ "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.

[ {"number": "420777777777", "text": "test1 <a>", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 <a>", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 <b> <d>", "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.

CLAVE	OBJETO DEL CANAL
`sms`	SMS
`viber`	Viber – promocional
`rcs`	RCS
`whatsapp`	WhatsApp

Ejemplos de solicitudes

Ejemplo de solicitud completa:

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 <a>", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 <a>", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 <b> <d>", "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:

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, <first_name> <last_name>", "schedule": "1526992636" }

Respuesta

En caso de éxito:

{ "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í.

En caso de error:

{ "type": "invalid_phone_number", "code": 400, "error": "Invalid phone number", "detail": null }

{ "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
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í.

¿Le ha resultado útil esta página?

Preguntar a la IA Copiado