Push Alerts API — Notifications to the mobile app (1.0)

Download OpenAPI specification:Download

INTRODUCTION

Send push alerts to your users' phones through our free application. Built for what cannot wait: an alarm, a critical incident, an authorisation someone has to give right now.



Unlike an SMS or an email, the alert can ring with the phone asleep and, if you mark it as critical, even with Do Not Disturb switched on. And you get to know whether it arrived, whether it was opened and whether it was accepted.

WHO YOU SEND TO: DEVICES AND ALIASES

Devices are linked from your panel (Alerts section), not through the API: that is where you generate linking codes —for yourself or for any of your authorized users, including staff who never log into the panel: hand them the code and all they need is the app—, see every device on your account and revoke them.



You can give each device an alias (warehouse-1, night-shift…): that alias is the REF parameter of EnviarPush. Without REF, the alert goes to every device on the account.



Groups are words inside the alias. If your devices are named warehouse-oncall-1, store-oncall-2…, then REFCONTIENE=oncall alerts the whole on-call group in a single call. Moving somebody to another group is just editing their alias in the panel (they change department, leave the on-call rota…) — nothing to register or maintain.



Your alerts also carry an application code (APLICACION parameter: alerta, aviso… whatever you invent). Each application shows up automatically in the panel as one more source, and the owner of each device chooses which sources each device receives: application alerta on phones 1 and 3, aviso on 1 and 2… No registration needed: the first time you send with one, it exists.

GETTING STARTED


1. In your panel, Alerts section, generate a linking code (for yourself or for an authorized user).
2. The person installs the alerts app and types that code.
3. Give the device an alias in the panel list (optional: without one it still receives account-wide alerts).
4. You can now send alerts with EnviarPush, with REF=alias for one device or without REF for all of them.



No password is ever typed into the app. The code lasts a few minutes, works once, and generating a new one voids the previous one. There are no user credentials for you to store or protect.

ALERT LEVELS

Each level is a separate notification channel on the phone, so the recipient can silence informational alerts and keep critical ones ringing without disabling the whole application.

LevelBehaviour on the phone
CRITICORings even with the volume down and bypasses Do Not Disturb, if the recipient granted the app that permission. Save it for what genuinely cannot wait: if everything is critical, nothing is.
ALTOSound and vibration, on the notification volume.
NORMALThe phone's usual notification sound. This is the default.
BAJOSilent. It just sits in the notification bar.

STATES

Every alert goes through up to four states. The last three are pushed to your server as they happen (see Receiving state changes):

StateWhat it actually means
ENVIADOSent. The push service accepted it into its queue. It says nothing about the phone.
ENTREGADODelivered. The app confirms it has displayed the alert. This one does depend on the phone, and it is the real difference between «we sent it» and «it appeared on their screen».
ABIERTOOpened. The recipient tapped it.
CONFIRMADOAcknowledged. They pressed Accept. Only if you asked for it with CONFIRMAR=1.


There is no «read» state, and that is deliberate: a notification is read on the lock screen without ever being touched, and there is no technical way to know. Calling «delivered» «read» would mislead you on a figure you are going to use to decide whether to alert someone again.



The states are set by the recipient's phone, not by us, so they arrive when that person picks up the device. That is why we push them to a script on your server as they happen, just like the rest of our APIs: switch it on in your panel and your system finds out immediately without making a single request.

PRICING

You are charged per recipient alerted, not per device: if that person has both a phone and a tablet linked, both receive the alert and you pay for one.



Generating codes, receiving state changes and managing devices cost no credits.

AUTHENTICATION

Same as the rest of our APIs: Basic authentication with your user and your API Token, which you will find in your panel under Your data → Configure → Security. Remember to authorise there the public IP address you will be calling from.

Send alert

/EnviarPush

Sends a push alert. With REF it goes to the devices carrying that alias; without REF, to every device on your account with this application enabled. If there is no recipient you get -6 and nothing is charged: link the device from your panel (Alerts section) and set the alias there.

Authorizations:
basicAuth
query Parameters
Ref
required
string
Example: Ref=user-4471

Alias of the target device, as set in your panel (device list in the Alerts section). Optional: without it, the alert goes to every device on the account. Maximum 64 characters.

Titulo
required
string
Example: Titulo=Alarm in warehouse 2

Title of the alert. This is what gets read in the notification, so make it stand on its own. Maximum 120 characters.

Mensaje
string
Example: Mensaje=Temperature sensor above 45 degrees since 03:12.

Body of the alert. Maximum 300 characters. Plain text: it goes to the phone's notification bar and does not accept HTML.

Nivel
string
Enum: "CRITICO" "ALTO" "NORMAL" "BAJO"
Example: Nivel=CRITICO

Alert level.
CRITICO - Critical. Rings even with the volume down and bypasses Do Not Disturb.
ALTO - High. Sound and vibration.
NORMAL - The phone's usual sound.
BAJO - Low. Silent.

Confirmar
string
Enum: 0 1
Example: Confirmar=1

Set to 1 if you want the alert to carry an Accept button and to record who pressed it and when. The recipient can accept straight from the notification, without opening the app.

Referenciausuario
string
Example: Referenciausuario=INC-99213

Your own free reference to match the alert against your system (a ticket number, an order number…). It comes back on every state-change report, letting you match it against your system without storing our idAviso. Maximum 50 characters.

Aplicacion
string
Example: Aplicacion=alerta

Application code grouping your alerts (alerta, aviso… lowercase, digits and dashes, maximum 20). No registration needed: the first time you send with one, it shows up in the recipient's panel as a source they can enable or disable per device. Defaults to api.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Response format.
JSON - Response in JSON
XML - Response in XML
TXT - Response in plain text

Refcontiene
string
Example: Refcontiene=oncall

Group sending: reaches every device whose alias contains this text (oncall reaches warehouse-oncall-1, store-oncall-2…). Mutually exclusive with REF: if you send both, REF wins. Maximum 64 characters.

Request Body schema:

Parameters are sent in the body of the POST request, either as a JSON object (Content-Type application/json, RECOMMENDED) or as an application/x-www-form-urlencoded form. In the form format, array or object parameters are sent as a JSON-encoded string. Parameter names are case-insensitive. The detailed description of each parameter is in the parameters section of this operation.

Ref
required
string
Titulo
required
string
Mensaje
string
Nivel
string
Confirmar
string
Referenciausuario
string
Aplicacion
string
Resp
string
Refcontiene
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Result of the call
>0 Number of recipients alerted.
-1 Authentication error or IP not authorised.
-2 Not enough credits.
-3 Parameter error. Details in Error.
-6 No device with that alias (or none with this application enabled). Nothing has been charged.

idAviso
integer

Alert identifier. Keep it: it travels on every state-change report so you can tie it back to the send.

Cred
number

Credits left after the send.

Error
string

Description of the problem when Res is negative.

Request samples

Content type
{
  • "Ref": "user-4471",
  • "Titulo": "Alarm in warehouse 2",
  • "Mensaje": "Temperature sensor above 45 degrees since 03:12.",
  • "Nivel": "CRITICO",
  • "Confirmar": "1",
  • "Referenciausuario": "INC-99213",
  • "Aplicacion": "alerta",
  • "Resp": "JSON",
  • "Refcontiene": "oncall"
}

Response samples

Content type
[
  • {
    }
]

Receiving state changes

https://{YourDomain}/path/to/your/report/receiver/script

REAL-TIME STATE CHANGES DELIVERED TO A SCRIPT ON YOUR SERVER.

Switch on report delivery to your own script in your panel and we will send a POST request every time one of your alerts changes state: when it is delivered, when it is opened and when it is acknowledged.



This is the recommended way to track your alerts. The states are not set by us but by the recipient's phone, so polling gains you nothing: they arrive when that person picks up the device. With reports, your system finds out the moment it happens and without making a single request.



You get one POST per change, not one with the final state: if an alert is delivered and opened almost at once you will receive both, which keeps the timestamp of each step. If your server does not respond we retry on later passes; after a few failed attempts we give up on that alert, so a server outage does not block the queue for everything else.



Reply 2xx. It is the same script and the same format you already use for SMS, Email or RCS reports: tell them apart by the Servicio field, which here is PUSH.

Authorizations:
basicAuth
Request Body schema:

Parámetros recibidos en su script en petición POST con la configuración especificada en su panel de usuario/configuración API.

Servicio
required
string

Type of report you are receiving, so you can tell it apart from other services in the same script.

PUSH Push alert state change

Resultado
required
string

New state of the alert.

STATEMEANING
`ENTREGADO`Delivered. The app confirms it has displayed the alert on the recipient's screen.
`ABIERTO`Opened. The recipient tapped it.
`CONFIRMADO`Acknowledged. They pressed Accept. Only on alerts sent with CONFIRMAR=1.
idAviso
required
integer

Alert identifier, the same one EnviarPush returned.

Ref
required
string

Reference of the recipient in your system.

Referencia
string

The REFERENCIAUSUARIO you supplied when sending, to match it against your system without storing our idAviso.

Titulo
string

Title of the alert, so you can identify it in your log without querying anything.

Nivel
string

Level it was sent with: CRITICO, ALTO, NORMAL or BAJO.

Fecha
required
string

When THIS state change happened (Spanish mainland time).

FechaEnvio
string

When the alert was sent. The gap against Fecha is how long the phone took to react.

Dispositivos
integer

Number of devices the alert went out to.

Request samples

Content type
{
  • "Servicio": "PUSH",
  • "Resultado": "ENTREGADO",
  • "idAviso": "84213",
  • "Ref": "user-4471",
  • "Referencia": "INC-99213",
  • "Titulo": "Alarm in warehouse 2",
  • "Nivel": "CRITICO",
  • "Fecha": "2026-08-05 03:14:06",
  • "FechaEnvio": "2026-08-05 03:14:02",
  • "Dispositivos": "2"
}

Devices

/DispositivosPush

Lists the devices on your account (all of them, or those carrying one alias with REF), or unlinks the devices of an alias. Useful to know whether somebody can receive alerts before sending any, and to remove people who stop working with you. BAJA requires REF: unlinking the whole account in one call would be too easy to do by accident. Costs no credits.

Authorizations:
basicAuth
query Parameters
Ref
required
string
Example: Ref=user-4471

Identifier of the user in YOUR system.

Accion
string
Enum: "CONSULTAR" "BAJA"
Example: Accion=CONSULTAR

What to do.
CONSULTAR - Returns the linked devices.
BAJA - Unlinks the devices of that REF (required). They stop receiving alerts immediately.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Response format.
JSON - Response in JSON
XML - Response in XML
TXT - Response in plain text

Request Body schema:

Parameters are sent in the body of the POST request, either as a JSON object (Content-Type application/json, RECOMMENDED) or as an application/x-www-form-urlencoded form. In the form format, array or object parameters are sent as a JSON-encoded string. Parameter names are case-insensitive. The detailed description of each parameter is in the parameters section of this operation.

Ref
required
string
Accion
string
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Result of the call
>=0 Number of devices returned (CONSULTAR) or unlinked (BAJA). A 0 on CONSULTAR means that person has not linked a phone yet.
-1 Authentication error or IP not authorised.
-3 Parameter error.

Dispositivos
Array of arrays

Linked devices. RetrasoSeg is how many seconds the last alert took to actually appear on screen after being sent: a high figure gives away a phone with aggressive battery saving, and explains why that person gets their alerts late.

Desvinculados
integer

Devices unlinked, when ACCION is BAJA.

Request samples

Content type
{
  • "Ref": "user-4471",
  • "Accion": "CONSULTAR",
  • "Resp": "JSON"
}

Response samples

Content type
[
  • {
    }
]