# Send Notifications

{% hint style="success" %}
This section describes API to send push notifications.
{% endhint %}

### Send Push <a href="#send-push" id="send-push"></a>

To send push notifications.

On success, the endpoint confirms that the notification has been queued and delivery has started. To check the delivery status, use the `notificationId` from the response with [#send-push-1](#send-push-1 "mention") endpoint.

#### Endpoint <a href="#http-request" id="http-request"></a>

`POST https://app.mpush.cloud/api/send`

#### Parameters (JSON) <a href="#parameters-json" id="parameters-json"></a>

| Key                        | Type   | Required | Description                                                                                                                 |
| -------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| topics                     | array  | Yes      | Contains a list of all topics to send the push to.                                                                          |
| payload.title              | string | No       | Notification title.                                                                                                         |
| payload.body               | string | Yes      | Notification body.                                                                                                          |
| payload.badge              | int    | No       | Badge number.                                                                                                               |
| payload.sound              | string | No       | Specify the sound path to play when the push arrives.                                                                       |
| payload.title\_loc\_key    | string | No       | Specify the key to a *body* string in a localization file for the current locale.                                           |
| payload.title\_loc\_args   | array  | No       | Specify the values to appear in place of the format specifiers in `title_loc_key`.                                          |
| payload.loc\_key           | string | No       | Specify the key to a *title* string in a localization file for the current locale.                                          |
| payload.loc\_args          | array  | No       | Specify the values to appear in place of the format specifiers in `loc_key`.                                                |
| payload.action\_loc\_key   | string | No       | Custom sound to play.                                                                                                       |
| payload.launch\_image      | string | No       | Specify the image path to launch at the app launch.                                                                         |
| payload.mutable\_content   | bool   | No       | Mutable content (**only iOS**).                                                                                             |
| payload.content\_available | bool   | No       | Content available (**only iOS**).                                                                                           |
| payload.category           | string | No       | Specify a category (**only iOS**).                                                                                          |
| payload.thread\_id         | int    | No       | Specify a thread (**only iOS**).                                                                                            |
| payload.collapse\_id       | int    | No       | Multiple notifications with the same collapse identifier are displayed to the user as a single notification (**only iOS**). |
| payload.expiration\_at     | int    | No       | A UNIX timestamp (UTC) that identifies the date when the notification is no longer valid and can be discarded.              |
| payload.custom             | object | No       | An object containing custom data.                                                                                           |

This table is used the "dot" notation to show the payload JSON structure.

For a complete reference to all available values to include in the payload we remand to the official documentation: [iOS](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html#//apple_ref/doc/uid/TP40008194-CH17-SW1) and [Android](https://firebase.google.com/docs/cloud-messaging/server).

#### Example <a href="#http-request" id="http-request"></a>

This API requires a **JSON payload**.

```php
curl https://app.mpush.cloud/api/send
-X POST 
-H "Accept: application/json" 
-H "Content-Type: application/json" 
-H "X-MPush-Token: <token>" 
-H "X-MPush-Token: 2" 
-d '<JSON payload>' 
```

On success is returned an HTTP 200 and JSON like this:

```php
{
  "notificationId": "18f7c750-5cde-4900-84db-2a863afebb91",
  "status": "accepted",
  "message": "Notification queued for processing"
}
```

#### Payload examples <a href="#examples" id="examples"></a>

Payload example to send a basic notification:

```php
{
  "topics": ["all"],
  "payload": {
    "body": "Hello"
  }
}
```

Payload example to send a basic notification to multiple topics with custom badge and sound:

```php
{
  "topics": ["news", "user.12", "user.15"],
  "payload": {
    "title": "News!",
    "body": "Hello",
    "badge": 2,
    "sound": "sound.aiff"
  }
}
```

Payload example to send a notification with an image:

```php
{
  "topics": ["project.all"],
  "payload": {
    "body": "Message with Image",
    "mutable_content": 1,
    "custom": {
      "media_url": "https://link-to-image.com"
    }
  }
}
```

Payload example to send a notification with localization:

```php
{
  "topics": ["user.23"],
  "payload": {
    "loc_key": "LOCALIZED_PUSH",
    "loc_args": [
      "Name",
      "Surname"
    ]
  }
}
```

### Notification Status <a href="#send-push" id="send-push"></a>

To retrieve the sending status.

When the `status` value becomes `completed`, it means the system has finished sending the notification.

#### Endpoint <a href="#http-request" id="http-request"></a>

`GET https://app.mpush.cloud/api/notifications/<notificationId>`

#### Example:

```php
curl https://app.mpush.cloud/api/notifications/<notificationId>
-H "Accept: application/json" 
-H "X-MPush-Token: <token>" 
-H "X-MPush-Token: 2"
```

On success is returned an HTTP 200 and JSON like this:

```php
{
  "projectId": 1,
  "failedCount": 10,
  "status": "completed",
  "createdAt": 1764100807728,
  "priority": "normal",
  "totalDevices": 1064,
  "topics": [
    "project.all"
  ],
  "notification": {
    "badge": 1,
    "title": "Title",
    "body": "Message"
  },
  "completedAt": 1764100816175,
  "sentCount": 1054,
  "iosCount": 736,
  "updatedAt": 1764100816141,
  "androidCount": 328,
  "id": "18f7c750-5cde-4900-84db-2a863afebb91"
}
```