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.

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key.

Endpoints Overview

The Karibu Messages API supports the following endpoints:

Endpoint	Method	Description
`/v1/message/send-instant`	POST	Sends an instant message to one or multiple recipients.
`/v1/message/send-campaign`	POST	Sends a message to all contacts in a campaign.
`/v1/message/logs`	GET	Fetches all message logs for the authenticated user.
`/v1/message/history`	GET	Retrieves all messages sent by the authenticated user.
`/v1/message/history/recipient/{recipient}`	GET	Retrieves all messages sent to a specific recipient.
`/v1/message/message-log/{message_id}`	GET	Retrieves 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

Field	Type	Required	Description
`content`	string	Yes	Message content.
`recipients`	array of strings	Yes	List of recipient phone numbers (e.g., `255788344348`).
`sender_id`	string	Yes	Sender ID for the message.
`campaign_id`	string or null	No	Campaign ID associated with the message.
`groups`	array of strings or null	No	List of group IDs for recipients.

Response fields

Field	Type	Description
`success`	boolean	Whether the request was accepted for queuing.
`job_id`	string	Id for this send job. Match webhook `data.job_id` to correlate callbacks with this response (see Webhooks).
`status`	string	High-level outcome (e.g. `sent` when queued for delivery).
`message`	string	Human-readable summary.
`stats`	object	Counts such as `recipients`, `sms_parts`, `total_sms`, `cost` (exact keys depend on deployment).
`meta`	object	Metadata such as `http_code`, `internal_code`, `description`.

Request Example

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

Response Example

{
  "success": true,
  "job_id": "instant--c0646f43-13c5-4258-bb16-3def2d4c16e8-1776068436.219251",
  "status": "sent",
  "message": "Instant message queued for 1 recipients",
  "stats": {
    "recipients": 1,
    "sms_parts": 1,
    "total_sms": 1,
    "cost": 1
  },
  "meta": {
    "http_code": 200,
    "internal_code": "OK",
    "description": "The request was successful."
  }
}

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

Field	Type	Required	Default	Description
`campaign_id`	string	Yes	—	Campaign ID for the message.
`group_id`	string	Yes	—	Group ID for the campaign recipients.
`content`	string	Yes	—	Message content.
`sender_id`	string	Yes	—	Sender ID (2–13 characters).
`start_date`	string or null	No	`"2025-08-23T02:22:43.202062"`	When sending starts (ISO 8601 format).
`end_date`	string or null	No	—	When sending ends (ISO 8601 format).
`frequency`	string or null	No	`"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

Field	Type	Required	Description
`recipient`	string	Yes	Recipient 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

Field	Type	Required	Description
`message_id`	string	Yes	Unique 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
}

​Karibu Messages API Documentation

​Authentication

​Endpoints Overview

​1. Send Instant Message

​Endpoint

​Request Body

​Response fields

​Request Example

​Response Example

​Error Response (422)

​2. Send Campaign Message

​Endpoint

​Request Body

​Request Example

​Response Example

​Error Response (422)

​3. Get Message Logs

​Endpoint

​Response Example

​Error Response (422)

​4. Get User Messages

​Endpoint

​Response Example

​Error Response (422)

​5. Get Messages By Recipient

​Endpoint

​Path Parameters

​Response Example

​Error Response (422)

​6. Get Message Detail

​Endpoint

​Path Parameters

​Response Example

​Error Response (422)

​Standard Response Format

Karibu Messages API Documentation

Authentication

Endpoints Overview

1. Send Instant Message

Endpoint

Request Body

Response fields

Request Example

Response Example

Error Response (422)

2. Send Campaign Message

Endpoint

Request Body

Request Example

Response Example

Error Response (422)

3. Get Message Logs

Endpoint

Response Example

Error Response (422)

4. Get User Messages

Endpoint

Response Example

Error Response (422)

5. Get Messages By Recipient

Endpoint

Path Parameters

Response Example

Error Response (422)

6. Get Message Detail

Endpoint

Path Parameters

Response Example

Error Response (422)

Standard Response Format