API reference
Notifications
3 operations. Base URL: https://api.ringura.com/api/v1. Authenticate with a bearer token that carries the scope named on each operation.
POST /api/v1/notifications
Send an order update, reminder or one-time code on WhatsApp (an approved template), SMS or e-mail, in the recipient's preferred order with fallback. The message lands on the contact's timeline; a reply routes to agents.
Parameters
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
Idempotency-Key | header | string | No | matches ^[A-Za-z0-9_.:-]{8,100}$ |
Request body
JSON (Content-Type: application/json).
| Field | Type | Required | Constraints |
|---|---|---|---|
contactId | string (uuid) | No | |
to | object | No | |
to.phone | string | No | matches ^[+][1-9][0-9]{6,14}$ |
to.email | string | No | at most 320 characters |
purpose | string | Yes | one of "utility", "authentication" |
channels | array of string | Yes | at least 1 items at most 3 items |
reference | string | No | 1-200 characters |
whatsapp | object | No | |
whatsapp.template | object | Yes | |
whatsapp.template.name | string | Yes | at most 512 characters |
whatsapp.template.language | string | Yes | at most 20 characters |
whatsapp.template.category | string | No | one of "utility", "authentication" |
whatsapp.template.parameters | array of string | No | at most 20 items |
sms | object | No | |
sms.body | string | Yes | 1-1600 characters |
email | object | No | |
email.subject | string | Yes | 1-300 characters |
email.body | string | Yes | 1-20000 characters |
Response
201 JSON with these fields.
| Field | Type | Required | Constraints |
|---|---|---|---|
id | string (uuid) | Yes | |
contactId | string (uuid) | Yes | |
purpose | string | Yes | one of "utility", "authentication" |
reference | string or null | Yes | |
status | string | Yes | one of "sent", "failed" |
channel | string or null | Yes | |
messageId | string (uuid) or null | Yes | |
interactionId | string (uuid) or null | Yes | |
attempts | array of object | Yes | |
attempts[].channel | string | Yes | |
attempts[].outcome | string | Yes | |
attempts[].reason | string or null | Yes | |
createdAt | string (date-time) | Yes |
Errors
400, 401, 403, 404, 409, 422, 429. What each status means
Example request
curl -X POST 'https://api.ringura.com/api/v1/notifications' \
-H "Authorization: Bearer $CC_TOKEN" \
-H 'Idempotency-Key: order-2027-0001' \
-H 'Content-Type: application/json' \
-d '{
"purpose": "utility",
"channels": [
"whatsapp"
]
}'GET /api/v1/notifications/{id}
One notification with every channel tried.
Parameters
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
id | path | string (uuid) | Yes |
Response
200 JSON with these fields.
| Field | Type | Required | Constraints |
|---|---|---|---|
id | string (uuid) | Yes | |
contactId | string (uuid) | Yes | |
purpose | string | Yes | one of "utility", "authentication" |
reference | string or null | Yes | |
status | string | Yes | one of "sent", "failed" |
channel | string or null | Yes | |
messageId | string (uuid) or null | Yes | |
interactionId | string (uuid) or null | Yes | |
attempts | array of object | Yes | |
attempts[].channel | string | Yes | |
attempts[].outcome | string | Yes | |
attempts[].reason | string or null | Yes | |
createdAt | string (date-time) | Yes |
Errors
400, 401, 403, 404, 409, 429. What each status means
Example request
curl -X GET 'https://api.ringura.com/api/v1/notifications/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e' \
-H "Authorization: Bearer $CC_TOKEN"PUT /api/v1/contacts/{id}/notification-preferences
A contact's preferred channel order and the channels it opted out of.
Parameters
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
id | path | string (uuid) | Yes | |
Idempotency-Key | header | string | No | matches ^[A-Za-z0-9_.:-]{8,100}$ |
Request body
JSON (Content-Type: application/json).
| Field | Type | Required | Constraints |
|---|---|---|---|
channels | array of string | No | at most 3 items |
optedOut | array of string | No | at most 3 items |
Response
200 JSON with these fields.
| Field | Type | Required | Constraints |
|---|---|---|---|
contactId | string (uuid) | Yes | |
channels | array of string | Yes | |
optedOut | array of string | Yes |
Errors
400, 401, 403, 404, 409, 422, 429. What each status means
Example request
curl -X PUT 'https://api.ringura.com/api/v1/contacts/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e/notification-preferences' \
-H "Authorization: Bearer $CC_TOKEN" \
-H 'Idempotency-Key: order-2027-0001' \
-H 'Content-Type: application/json' \
-d '{
"channels": [
"whatsapp"
]
}'