Send a push notification to a user's devices

# Copy for LLM

Sends a notification to every active device token of one user. The PBX is authenticated by pbx_id plus api_key in the body, not by a header.

A data.notif_type of microsoft_graph routes to the user's Microsoft Teams activity feed instead of their devices, and queues the delivery. It requires an active, admin-consented Microsoft 365 integration with the "Push notifications to Teams" switch on; otherwise nothing is sent and the response reports zero notifications.

A data.notif_type of cancelled is accepted and ignored.

Authorization Headers

HTTP: PbxServerAuth

Auth for Pbx server

HTTP Authorization Scheme

bearer

Bearer format

Bearer <token>

accept header · string

example: application/json

Request body · required · application/json

Request schema

Expand allCollapse all

pbx_id*string · uuid

The PBX the user belongs to.

example: 3f8c2b1e-5d47-4a90-b6e2-9c1f0d7a4b33

api_key*string

That PBX's API key.

example: 9f2c14d8e7b3a05614c8f27d3b9e6a41

user_id*string · uuid

Recipient. Must belong to the authenticated PBX.

example: 7d1b4a92-3c68-4f57-9e20-8b5c1d0a6f74

twinningNumbersarray<string>

Restricts delivery to these twinning numbers.

nullable

[]string

envstring

APNs environment. Defaults to production.

nullable

enum: production development staging

example: production

data*object

The notification payload, passed through to APNs and FCM.

notif_type*string

What kind of notification this is. `microsoft_graph` targets Teams, `cancelled` is ignored, everything else targets the user's devices.

enum: precall incoming missed callog_incoming callog_missed cancelled microsoft_graph

example: incoming

caller_namestring

Caller's display name, urlencoded.

example: Jane%20Doe

calling_numberstring

Caller's number.

example: +35220123456

full_numberstring

Caller's number in full international form, urlencoded.

example: %2B35220123456

usernamestring

Callee's display name, used in the device alert text.

example: Alex Turner

titlestring

Overrides the composed headline. Teams and Tempus payloads.

example: Incoming call

messagestring

Overrides the composed body. Teams and Tempus payloads.

example: Call from Jane Doe

web_url_contextstring

Teams only. Passed to the Teams app as the deep link's `subEntityId`, so a click can open this specific call.

example: call-4821

Responses

200 401 404 422 5XX

The notifications were processed. A device send that failed for every token answers 500 instead; zero tokens, or Teams push switched off, is still a 200 with nothing sent.

Response schema

Expand allCollapse all

messagestring

dataobject

notification_statusobject

One entry per delivered device notification. For a Teams notification this is an object reporting that it was queued.

summaryobject

total_sentinteger

total_failedinteger

failed_tokensarray<object>

token_idstring · uuid

device_idstring

errorstring

`pbx_id` and `api_key` do not identify a PBX. The two are checked together, so an unknown PBX and a wrong key are indistinguishable.

Response schema

messagestring

`user_id` is not a user of the authenticated PBX. Returned on the Teams path, which resolves the recipient before queueing.

Response schema

messagestring

Unprocessable Parameters. This error is returned when a parameter is not valid.

Response schema

Expand allCollapse all

messagestring

example: The given data was invalid.

errorsobject

filterarray<string>

[]string

sortarray<string>

[]string

pagearray<string>

[]string

per_pagearray<string>

[]string

Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue.

Response schema

messagestring

exceptionstring

Only present in non-production environments.

filestring

Only present in non-production environments.

lineinteger

Only present in non-production environments.

post https://cockpit.voxbi.com/api/v1/notify-device

Base URL The production API server The staging API server The development API server

Request sample cURL JavaScript Python PHP

Copy

curl -X POST 'https://cockpit.voxbi.com/api/v1/notify-device' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"pbx_id":"3f8c2b1e-5d47-4a90-b6e2-9c1f0d7a4b33","api_key":"9f2c14d8e7b3a05614c8f27d3b9e6a41","user_id":"7d1b4a92-3c68-4f57-9e20-8b5c1d0a6f74","env":"production","data":{"notif_type":"incoming","caller_name":"Jane%20Doe","calling_number":"+35220123456","username":"Alex Turner"}}'

Copy

const response = await fetch('https://cockpit.voxbi.com/api/v1/notify-device', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
  body: JSON.stringify({
    "pbx_id": "3f8c2b1e-5d47-4a90-b6e2-9c1f0d7a4b33",
    "api_key": "9f2c14d8e7b3a05614c8f27d3b9e6a41",
    "user_id": "7d1b4a92-3c68-4f57-9e20-8b5c1d0a6f74",
    "env": "production",
    "data": {
        "notif_type": "incoming",
        "caller_name": "Jane%20Doe",
        "calling_number": "+35220123456",
        "username": "Alex Turner"
    }
}),
});

const data = await response.json();
console.log(data);

Copy

import requests

response = requests.post('https://cockpit.voxbi.com/api/v1/notify-device',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
    json={
    "pbx_id": "3f8c2b1e-5d47-4a90-b6e2-9c1f0d7a4b33",
    "api_key": "9f2c14d8e7b3a05614c8f27d3b9e6a41",
    "user_id": "7d1b4a92-3c68-4f57-9e20-8b5c1d0a6f74",
    "env": "production",
    "data": {
        "notif_type": "incoming",
        "caller_name": "Jane%20Doe",
        "calling_number": "+35220123456",
        "username": "Alex Turner"
    }
}
)
response.raise_for_status()
data = response.json()
print(data)

Copy

<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
        'content' => '{
    \"pbx_id\": \"3f8c2b1e-5d47-4a90-b6e2-9c1f0d7a4b33\",
    \"api_key\": \"9f2c14d8e7b3a05614c8f27d3b9e6a41\",
    \"user_id\": \"7d1b4a92-3c68-4f57-9e20-8b5c1d0a6f74\",
    \"env\": \"production\",
    \"data\": {
        \"notif_type\": \"incoming\",
        \"caller_name\": \"Jane%20Doe\",
        \"calling_number\": \"+35220123456\",
        \"username\": \"Alex Turner\"
    }
}',
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/notify-device', false, $context);
$data = json_decode($response, true);
print_r($data);

Sample request

Expand all Collapse all Copy

{ … }

"pbx_id": "3f8c2b1e-5d47-4a90-b6e2-9c1f0d7a4b33",

"api_key": "9f2c14d8e7b3a05614c8f27d3b9e6a41",

"user_id": "7d1b4a92-3c68-4f57-9e20-8b5c1d0a6f74",

"env": "production",

"data": { … }

"notif_type": "incoming",

"caller_name": "Jane%20Doe",

"calling_number": "+35220123456",

"username": "Alex Turner"

}

}

Sample response Response headers

Expand all Collapse all Copy

{ … }

"message": "Notifications processed successfully.",

"data": { … }

"notification_status": [ … ],

{ … }

"name": "projects/voxbi/messages/0:1757000000000000%1a2b3c4d"

}

],

"summary": { … },

"total_sent": 1,

"total_failed": 0

},

"failed_tokens": []

}

}

Host string

example: cockpit.voxbi.com

Date string

example: Mon, 16 Oct 2023 14:08:48 GMT

Connection string

example: close

Cache-Control string

example: no-cache, private

Content-Type string

example: application/json

X-RateLimit-Limit integer

example: 60

X-RateLimit-Remaining integer

example: 59

Vary string

example: Origin

Sample response Response headers

Expand all Collapse all Copy

{ … }

"message": "Authentication failed"

}

Host string

example: cockpit.voxbi.com

Date string

example: Mon, 16 Oct 2023 14:08:48 GMT

Connection string

example: close

Cache-Control string

example: no-cache, private

Content-Type string

example: application/json

X-RateLimit-Limit integer

example: 60

X-RateLimit-Remaining integer

example: 59

Vary string

example: Origin

Sample response Response headers

Expand all Collapse all Copy

{ … }

"message": "User not found for this PBX"

}

Host string

example: cockpit.voxbi.com

Date string

example: Mon, 16 Oct 2023 14:08:48 GMT

Connection string

example: close

Cache-Control string

example: no-cache, private

Content-Type string

example: application/json

X-RateLimit-Limit integer

example: 60

X-RateLimit-Remaining integer

example: 59

Vary string

example: Origin

Sample response Response headers

Expand all Collapse all Copy

{ … }

"errors": { … }

"filter": [ … ],

"The filter field must be an array."

],

"sort": [ … ],

"The sort field must be a string."

],

"page": [ … ],

"The page field must be an integer."

],

"per_page": [ … ]

"The per page field must be an integer."

]

}

}

Cache-Control string

example: private, must-revalidate

Connection string

example: keep-alive

Content-Type string

example: application/json

Vary string

example: Origin

X-RateLimit-Limit integer

Max requests allowed in the current rate-limit window.

example: 60

X-RateLimit-Remaining integer

Requests remaining in the current rate-limit window.

example: 57

Sample response

Expand all Collapse all Copy

{ … }

"message": "Server Error"

}