Skip to main content

​
Karibu Messages API Documentation

The Karibu Messages API allows developers to send instant and campaign-based messages, retrieve message logs, and access message history for authenticated users or specific recipients. This API is designed for seamless integration into applications requiring messaging capabilities.

​
Authentication

All API endpoints require an X-API-Key header for authentication.
HeaderTypeRequiredDescription
X-API-KeystringYesYour API key.

​
Endpoints Overview

The Karibu Messages API supports the following endpoints:
EndpointMethodDescription
/v1/message/send-instantPOSTSends an instant message to one or multiple recipients.
/v1/message/send-campaignPOSTSends a message to all contacts in a campaign.
/v1/message/logsGETFetches all message logs for the authenticated user.
/v1/message/historyGETRetrieves all messages sent by the authenticated user.
/v1/message/history/recipient/{recipient}GETRetrieves all messages sent to a specific recipient.
/v1/message/message-log/{message_id}GETRetrieves details of a specific message.

​
1. Send Instant Message

Send an instant message to one or multiple recipients.

​
Endpoint

POST /v1/message/send-instant

​
Request Body

FieldTypeRequiredDescription
contentstringYesMessage content.
recipientsarray of stringsYesList of recipient phone numbers (e.g., 255788344348).
sender_idstringYesSender ID for the message.
campaign_idstring or nullNoCampaign ID associated with the message.
groupsarray of strings or nullNoList of group IDs for recipients.

​
Request Example

{
  "content": "Ping from Briq",
  "recipients": ["255788344348"],
  "sender_id": "string",
  "campaign_id": "string",
  "groups": ["group_id", "group_id"]
}

​
Response Example

{
  "success": true,
  "message": "Message sent successfully",
  "data": {},
  "status_code": 200
}

​
Error Response (422)

{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}

​
2. Send Campaign Message

Send a message to all contacts in a specified campaign.

​
Endpoint

POST /v1/message/send-campaign

​
Request Body

FieldTypeRequiredDefaultDescription
campaign_idstringYes—Campaign ID for the message.
group_idstringYes—Group ID for the campaign recipients.
contentstringYes—Message content.
sender_idstringYes—Sender ID (2–13 characters).
start_datestring or nullNo"2025-08-23T02:22:43.202062"When sending starts (ISO 8601 format).
end_datestring or nullNo—When sending ends (ISO 8601 format).
frequencystring or nullNo"once"Campaign frequency (e.g., once).

​
Request Example

{
  "campaign_id": "string",
  "group_id": "string",
  "content": "Campaign message from Briq",
  "sender_id": "string",
  "start_date": "2025-08-23T02:22:43.202062",
  "end_date": "2019-08-24T14:15:22Z",
  "frequency": "once"
}

​
Response Example

{
  "success": true,
  "message": "Campaign message sent successfully",
  "data": {},
  "status_code": 200
}

​
Error Response (422)

{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}

​
3. Get Message Logs

Fetch all message logs for the authenticated user.

​
Endpoint

GET /v1/message/logs

​
Response Example

{
  "user_id": "string",
  "logs": [{}],
  "success": true,
  "message": "Logs retrieved successfully",
  "status_code": 200
}

​
Error Response (422)

{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}

​
4. Get User Messages

Retrieve all messages sent by the authenticated user.

​
Endpoint

GET /v1/message/history

​
Response Example

[
  {
    "message_id": "string",
    "user_id": "string",
    "recipient": "string",
    "campaign_id": "string",
    "channel_id": "string",
    "sender_id": "string",
    "content": "string",
    "status": "pending",
    "sent_at": "2019-08-24T14:15:22Z"
  }
]

​
Error Response (422)

{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}

​
5. Get Messages By Recipient

Retrieve all messages sent to a specific recipient.

​
Endpoint

GET /v1/message/history/recipient/{recipient}

​
Path Parameters

FieldTypeRequiredDescription
recipientstringYesRecipient phone number.

​
Response Example

[
  {
    "message_id": "string",
    "user_id": "string",
    "recipient": "string",
    "campaign_id": "string",
    "channel_id": "string",
    "sender_id": "string",
    "content": "string",
    "status": "pending",
    "sent_at": "2019-08-24T14:15:22Z"
  }
]

​
Error Response (422)

{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}

​
6. Get Message Detail

Retrieve details of a specific message by its ID.

​
Endpoint

GET /v1/message/message-log/{message_id}

​
Path Parameters

FieldTypeRequiredDescription
message_idstringYesUnique message ID.

​
Response Example

{
  "message_id": "string",
  "user_id": "string",
  "recipient": "string",
  "campaign_id": "string",
  "channel_id": "string",
  "sender_id": "string",
  "content": "string",
  "status": "pending",
  "sent_at": "2019-08-24T14:15:22Z",
  "success": true,
  "message": "Message details retrieved successfully",
  "status_code": 200
}

​
Error Response (422)

{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}

​
Standard Response Format

Unless specified otherwise, successful responses follow this JSON format: 
{
  "success": true,
  "message": "string",
  "data": {},
  "status_code": 200
}
Error responses (e.g., 422 Validation Error) follow this format: 
{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}
⌘I