API reference
Detailed endpoint documentation.
Send SMS
Send a single transactional message to a specific phone number.
POSThttps://raven.et/api/api/v1/message/send
Parameters
| Property | Type | Description |
|---|---|---|
| sender* | string | Sender ID (UUID or registered name) |
| to_number* | string | Recipient phone number (E.164 format) |
| body* | string | Message content |
Example request
bash
curl -X POST "https://raven.et/api/api/v1/message/send" \
-H "X-API-Key: <API_KEY>" \
-d '{"sender":"UUID","to_number":"+251911111111","body":"Your verification code is 1234"}'Success response
json
{
"success": true,
"message_id": "msg_8989823",
"status": "queued"
}Send bulk SMS
Send the same message to multiple recipients efficiently.
POSThttps://raven.et/api/api/v1/message/send-bulk
| Property | Type | Description |
|---|---|---|
| sender* | string | Sender ID |
| to_numbers* | array<string> | Array of phone numbers |
| body* | string | Message content |
Example request
bash
curl -X POST "https://raven.et/api/api/v1/message/send-bulk" \
-H "X-API-Key: <API_KEY>" \
-d '{
"sender": "UUID",
"to_numbers": ["+251911000000", "+251922000000"],
"body": "Sale starts now!"
}'OTP services
Generate and verify one-time passwords.
1. Send OTP
POSThttps://raven.et/api/api/v1/otp/send
| Property | Type | Description |
|---|---|---|
| phone_number* | string | Recipient number |
| purpose* | string | Purpose of the OTP (e.g., login, register) |
json
{
"success": true,
"message": "OTP sent",
"expires_at": "2026-02-11T09:25:00.000Z"
}2. Verify OTP
POSThttps://raven.et/api/api/v1/otp/verify
| Property | Type | Description |
|---|---|---|
| phone_number* | string | Recipient number |
| code* | string | OTP code provided by the user |
json
{
"success": true,
"message": "OTP verified"
}Webhook services
Manage and receive webhook notifications for delivery events.
1. Create webhook
POSThttps://raven.et/api/api/v1/webhooks
| Property | Type | Description |
|---|---|---|
| event_types* | array<string> | Events to subscribe to (e.g., delivery.report, sms.failed) |
| url* | string | Public HTTPS endpoint that receives webhook notifications |
Example request
bash
curl -X POST "https://raven.et/api/api/v1/webhooks" \
-H "Content-Type: application/json" \
-d '{
"event_types": ["delivery.report", "sms.failed"],
"url": "https://example.com/webhooks/cheche"
}'Success response
json
{
"id": "wh_01hzyd9d6n1p7p6y9v5r",
"tenant_id": "ten_01hzyd82sv3s3d9yfq0j",
"url": "https://example.com/webhooks/cheche",
"event_types": [
"delivery.report",
"sms.failed"
],
"enabled": true,
"created_at": "2026-02-11T09:21:18.410Z"
}2. List webhooks
GEThttps://raven.et/api/api/v1/webhooks
Example request
bash
curl -X GET "https://raven.et/api/api/v1/webhooks"Success response
json
[
{
"id": "wh_01hzyd9d6n1p7p6y9v5r",
"tenant_id": "ten_01hzyd82sv3s3d9yfq0j",
"url": "https://example.com/webhooks/cheche",
"event_types": [
"delivery.report",
"sms.failed"
],
"enabled": true,
"created_at": "2026-02-11T09:21:18.410Z"
}
]3. Get webhook
GEThttps://raven.et/api/api/v1/webhooks/{id}
| Property | Type | Description |
|---|---|---|
| id* | string | Webhook identifier returned from creation |
Example request
bash
curl -X GET "https://raven.et/api/api/v1/webhooks/wh_01hzyd9d6n1p7p6y9v5r"Success response
json
{
"id": "wh_01hzyd9d6n1p7p6y9v5r",
"tenant_id": "ten_01hzyd82sv3s3d9yfq0j",
"url": "https://example.com/webhooks/cheche",
"event_types": [
"delivery.report",
"sms.failed"
],
"enabled": true,
"created_at": "2026-02-11T09:21:18.410Z"
}4. Update webhook
PUThttps://raven.et/api/api/v1/webhooks/{id}
| Property | Type | Description |
|---|---|---|
| id* | string | Webhook identifier returned from creation |
| url | string | New destination URL (omit to keep current) |
| event_types | array<string> | Replace subscribed events (minimum one when provided) |
| enabled | boolean | Enable or disable delivery for this webhook |
Example request
bash
curl -X PUT "https://raven.et/api/api/v1/webhooks/wh_01hzyd9d6n1p7p6y9v5r" \
-H "Content-Type: application/json" \
-d '{
"event_types": ["delivery.report"],
"enabled": false
}'Success response
json
{
"id": "wh_01hzyd9d6n1p7p6y9v5r",
"tenant_id": "ten_01hzyd82sv3s3d9yfq0j",
"url": "https://example.com/webhooks/cheche",
"event_types": [
"delivery.report"
],
"enabled": false,
"created_at": "2026-02-11T09:21:18.410Z"
}5. Delete webhook
DELETEhttps://raven.et/api/api/v1/webhooks/{id}
| Property | Type | Description |
|---|---|---|
| id* | string | Webhook identifier returned from creation |
Example request
bash
curl -X DELETE "https://raven.et/api/api/v1/webhooks/wh_01hzyd9d6n1p7p6y9v5r"Success response
json
"Deleted Sucess fully"6. Sample delivery event
Events are delivered as signed JSON payloads. Verify the X-Cheche-Signature header using the shared secret before processing.
json
{
"id": "evt_01hzyf3hrk59s13n6j1w",
"type": "delivery.report",
"created_at": "2026-02-11T09:30:44.213Z",
"data": {
"message_id": "msg_8989823",
"to_number": "+251911111111",
"status": "delivered",
"delivered_at": "2026-02-11T09:30:42.101Z"
}
}Reporting
Retrieve sent messages and view your remaining SMS balance.
1. Get SMS
GEThttps://raven.et/api/api/v1/message
Query parameters
| Property | Type | Description |
|---|---|---|
| page | number | Page number (default 1) |
| page_size | number | Page size (default 20) |
| status | string | Filter by message status |
Example request
bash
curl -X GET "https://raven.et/api/api/v1/message?page=1&page_size=20" \
-H "X-API-Key: <API_KEY>"Success response
json
{
"messages": [
{
"id": "msg_123",
"to_number": "+251911111111",
"body": "Your verification code is 1234",
"status": "delivered",
"segments": 1
}
],
"total": 1,
"page": 1,
"page_size": 20,
"total_pages": 1
}2. Get balance
GEThttps://raven.et/api/api/v1/analytics/summary
Example request
bash
curl -X GET "https://raven.et/api/api/v1/analytics/summary" \
-H "X-API-Key: <API_KEY>"Success response
json
{
"total_sent": 1240,
"delivery_rate": 98.7,
"failed_messages": 16,
"remaining_credits": 8500
}