API

Autenticación

Al realizar solicitudes de API, debe incluir su clave API en el encabezado HTTP. El formato del encabezado debería verse así:

X-TopMessage-Key: {API_KEY}

Administre sus claves API

aquí

Enviar mensajes

Envíe fácilmente uno o más mensajes a sus clientes a través de sus canales preferidos, como SMS y WhatsApp, utilizando una única API unificada. Comience con un simple mensaje de texto definiendo el destino y el contenido, o aproveche las funciones avanzadas para mejorar su estrategia de comunicación.

Ejemplos de casos de uso

Los siguientes son algunos ejemplos de casos de uso para la API TopMessage:

SMS sencillos
SMS personalizados
SMS con enlace acortado
Verificación por SMS
SMS con plantilla
WhatsApp con plantilla
Respuesta de formato libre de WhatsApp
Mensaje programado
Mensajes masivos

Parámetros de solicitud completos

Nombre	Amable	Descripción
data	`object`	Contiene los siguientes detalles del mensaje que se envía.

Objeto de datos

Nombre	Amable	Descripción
from	`string`	Nombre de remitente desde el cual se enviará tu mensaje. Puedes ver los nombres disponibles o crear uno nuevo en la página de remitentes.Ir a la página de remitentes.
to	`string[]`	Número(s) de teléfono móvil del destinatario en formato internacional.
text	`string`	Su mensaje de texto se enviará a los destinatarios.
channel	`string`	El canal de comunicación envía su mensaje. Valores posibles: `SMS` y `WHATSAPP` Por defecto: `SMS`
template_id	`string`	Identificador único de tu plantilla enviada. Puedes ver las plantillas disponibles o crear una nueva desde tu cuenta en la página de plantillas.Ir a la página de plantillas.
parameters	`string[]`	Estos valores se utilizan para reemplazar los marcadores de posición en su plantilla de mensaje, lo que le permite personalizar el mensaje para cada destinatario. Por defecto: Vacío
shorten_URLs	`boolean`	Indica si las URL HTTPS en el texto deben reemplazarse con URL acortadas. Valores posibles: `TRUE` y `FALSE` Por defecto: `FALSE`
request_id	`string`	Identificador único de solicitud generada por usted para rastrear solicitudes. Por defecto: `NULL`
schedule	`string`	Especifica la hora en que se debe enviar el mensaje. La hora debe estar en UTC y seguir el formato ISO-8601 ("2024-12-01T18:00:00Z"). La hora programada no puede establecerse a más de 1 año en el futuro. Por defecto: Ahora

Parámetros de respuesta completos

Parámetros de respuesta

La respuesta incluye todos los parámetros de la solicitud, junto con los parámetros adicionales que se enumeran a continuación.

Objeto de datos

Nombre	Amable	Descripción
account_id	`string`	Identificador único de su cuenta.
id	`string`	Identificador único de su mensaje.
status	`string`	Estado inicial de su mensaje. Valores posibles: `PENDING`, `FAILED`, `DELIVERED`, `SEEN`
create_date	`string`	Hora en que se inició el mensaje
update_date	`string`	Fecha de la última actualización de estado de su mensaje.
segment_count	`integer`	El número de segmentos que componían su mensaje.
encoding	`string`	Codificación de su mensaje. Valores posibles: `STANDARD` y `UNICODE`

POST

https://api.topmessage.es/v1/messages

X-TopMessage-Key: {API_KEY}
Content-Type: application/json

Solicitar muestra

Payload

cURL

Java

Python

{
    "data": {
        "from": "TopMessage",
        "to": [
            "48727516980",
            "48727516981"
        ],
        "parameters": {
            "48727516980": ["John"],
            "48727516981": ["Ann"]
        },
        "text": "Hi {first_name}! Just testing out this cool SMS feature.https://topmessage.com",
        "shorten_URLs": true,
        "request_id": "9190cda0-70d8-4127-ac8f-787c083efa1b",
        "schedule": "2024-12-01T00:00:01Z"
    }
}

curl -X POST "https://api.topmessage.com/v1/messages" -H "Content-Type: application/json" -H "X-TopMessage-Key: {API_KEY}" -d '{
    "data": {
        "from": "TopMessage",
        "to": [
            "48727516980",
            "48727516981"
        ],
        "parameters": {
            "48727516980": ["John"],
            "48727516981": ["Ann"]
        },
        "text": "Hi {first_name}! Just testing out this cool SMS feature.https://topmessage.com",
        "request_id": "9190cda0-70d8-4127-ac8f-787c083efa1b",
        "shorten_URLs": true,
        "schedule": "2024-12-01T00:00:01Z"
     }
  }'

String response = HttpClient.newHttpClient().send(
    HttpRequest.newBuilder()
        .uri(URI.create("https://api.topmessage.com/v1/messages"))
        .header("Content-Type", "application/json")
        .header("X-TopMessage-Key", "{API_KEY}")
        .POST(HttpRequest.BodyPublishers.ofString("""
            {
                "data": {
                    "from": "TopMessage",
                    "to": [
                        "48727516980",
                        "48727516981"
                    ],
                    "parameters": {
                        "48727516980": ["John"],
                        "48727516981": ["Ann"]
                    },
                    "text": "Hi {first_name}! Just testing out this cool SMS feature. https://topmessage.com",
                    "request_id": "9190cda0-70d8-4127-ac8f-787c083efa1b",
                    "shorten_URLs": true,
                    "schedule": "2024-12-01T00:00:01Z"
                }
            }
            """))
        .build(),
    HttpResponse.BodyHandlers.ofString()
).body();

response = requests.post(
    "https://api.topmessage.com/v1/messages",
    headers={
        "Content-Type": "application/json",
        "X-TopMessage-Key": "{API_KEY}"
    },
    json={
       "data": {
            "from": "TopMessage",
            "to": ["48727516980", "48727516981"],
            "parameters": {
                "48727516980": ["John"],
                "48727516981": ["Ann"]
            },
            "text": "Hi {first_name}! Just testing out this cool SMS feature.https://topmessage.com",
            "request_id": "9190cda0-70d8-4127-ac8f-787c083efa1b",
            "shorten_URLs": true,
            "schedule": "2024-12-01T00:00:01Z"
        }
    }
)

Muestra de respuesta

{
    "data": [
        {
            "id": "0f15fa5d-97ef-46d5-844a-f507f1c4c461",
            "account_id": "0d1f7f1c-27df-41bf-8bdc-5666608a4285",
            "template_id": "7c3f35bc-491e-4580-a8b8-602efae1ccd1",
            "status": "PENDING",
            "from": "TopMessage",
            "to": "48727516980",
            "text": "Hi {first_name}! Just testing out this cool SMS feature. https://topmessage.com",
            "parameters": [
                "John"
            ],
            "channel": "SMS",
            "segment_count": 1,
            "encoding": "STANDARD",
            "schedule": "2024-11-20T08:11:46Z",
            "create_date": "2024-11-25T06:58:22Z",
            "update_date": "2024-11-25T06:58:22Z"
        },
        {
            "id": "6fc214dc-4e51-4fce-bc0a-324a1d8a542b",
            "account_id": "0d1f7f1c-27df-41bf-8bdc-5666608a4285",
            "template_id": "7c3f35bc-491e-4580-a8b8-602efae1ccd1",
            "status": "PENDING",
            "from": "TopMessage",
            "to": "48727516981",
            "text": "Hi {first_name}! Just testing out this cool SMS feature.",
            "parameters": [
                "Ann"
            ],
            "channel": "SMS",
            "segment_count": 1,
            "encoding": "STANDARD",
            "schedule": "2024-11-20T08:11:46Z",
            "create_date": "2024-11-25T06:58:22Z",
            "update_date": "2024-11-25T06:58:22Z"
        }
    ]
}