> ## Documentation Index
> Fetch the complete documentation index at: https://docs.briq.tz/llms.txt
> Use this file to discover all available pages before exploring further.

# Index

# 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

```http theme={null}
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](/guides/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

```json theme={null}
{
  "content": "Ping from Briq",
  "recipients": ["255788344348"],
  "sender_id": "string",
  "campaign_id": "string",
  "groups": ["group_id", "group_id"]
}
```

### Response Example

```json theme={null}
{
  "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)

```json theme={null}
{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}
```

***

## 2. Send Campaign Message

Send a message to all contacts in a specified campaign.

### Endpoint

```http theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "success": true,
  "message": "Campaign message sent successfully",
  "data": {},
  "status_code": 200
}
```

### Error Response (422)

```json theme={null}
{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}
```

***

## 3. Get Message Logs

Fetch all message logs for the authenticated user.

### Endpoint

```http theme={null}
GET /v1/message/logs
```

### Response Example

```json theme={null}
{
  "user_id": "string",
  "logs": [{}],
  "success": true,
  "message": "Logs retrieved successfully",
  "status_code": 200
}
```

### Error Response (422)

```json theme={null}
{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}
```

***

## 4. Get User Messages

Retrieve all messages sent by the authenticated user.

### Endpoint

```http theme={null}
GET /v1/message/history
```

### Response Example

```json theme={null}
[
  {
    "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)

```json theme={null}
{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}
```

***

## 5. Get Messages By Recipient

Retrieve all messages sent to a specific recipient.

### Endpoint

```http theme={null}
GET /v1/message/history/recipient/{recipient}
```

### Path Parameters

| Field       | Type   | Required | Description             |
| ----------- | ------ | -------- | ----------------------- |
| `recipient` | string | Yes      | Recipient phone number. |

### Response Example

```json theme={null}
[
  {
    "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)

```json theme={null}
{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}
```

***

## 6. Get Message Detail

Retrieve details of a specific message by its ID.

### Endpoint

```http theme={null}
GET /v1/message/message-log/{message_id}
```

### Path Parameters

| Field        | Type   | Required | Description        |
| ------------ | ------ | -------- | ------------------ |
| `message_id` | string | Yes      | Unique message ID. |

### Response Example

```json theme={null}
{
  "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)

```json theme={null}
{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}
```

***

## Standard Response Format

Unless specified otherwise, successful responses follow this JSON format:

```json theme={null}
{
  "success": true,
  "message": "string",
  "data": {},
  "status_code": 200
}
```

Error responses (e.g., 422 Validation Error) follow this format:

```json theme={null}
{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}
```