# Introduction

Welcome to the OneRoute API Documentation where you find information, best practices, and guidance about the OneRoute API.

### Prerequisites

The prerequisites list everything you need to do to gain access to the OneRoute APIs.

{% content-ref url="/pages/ZavcJ8YIJQAbyA4qkTBY" %}
[Prerequisites](/prerequisites)
{% endcontent-ref %}

Using the [OneRoute](https://oneroute.io/) API documentation, you can send and receive messages from customers via the supported channels.

### WhatsApp

The WhatsApp Business API enables you to reliably send and receive Whatsapp messages to/from your customers.

{% content-ref url="/pages/NnnSP30Mxu2acQ5Y7awM" %}
[Getting Started](/whatsapp-api/getting-started)
{% endcontent-ref %}

### SMS

The SMS API enables you to send messages to your customers via SMS.

{% content-ref url="/pages/-Mgmd0x58g-LLjxSO-SY" %}
[Endpoints](/sms-api/sms-api)
{% endcontent-ref %}

### OneOTP

The OneOTP API allows you to reliably send One-Time Passwords via SMS, Whatsapp, Email, USSD, and Voice from a single, robust API.

{% content-ref url="/pages/-Ml9GIS9Uf3yVpNNf0Ds" %}
[Endpoints](/oneotp-api/oneotp-api)
{% endcontent-ref %}


# Prerequisites

Everything you need to do to gain access to the OneRoute APIs

### 1. Create a OneRoute account

* Go to <https://app.oneroute.io/sign-up>
* Provide the necessary personal and company information including a valid work email.
* Verify your account from the verification email sent to your email address.

![OneRoute - Sign Up](/files/-Mfm4nF1J0wgn2t_Xyzn)

### 2. Get your OneRoute API key

* To get your OneRoute API Key, navigate to **Settings** > **Account Settings**
* You would be able to see: **API Key**, Secret Key, and Webhook Url.
* Copy the **API Key**, and proceed.

![OneRoute - Account Settings](/files/Lbr2k8RXZlSxuXxQqo19)

### 3. Top-up your Wallet

* To top up your wallet, navigate to **Settings** > **Billing**.&#x20;
* Click the Top-up button and enter the amount you would like to top-up.&#x20;
* Click Proceed to make the necessary payments.

![OneRoute - Top-up wallet](/files/90edKiXc6Ufo222qj6JF)


# Sandbox (Test API Key)

OneRoute provides a developer-friendly test environment to check out the usage of the WhatsApp API. Through the test channel, you can test sending messages and templates and receive a webhook.

{% hint style="success" %}
**What you can do in the Sandbox**&#x20;

1. You can use the Test **`API Key`** to send`text` **messages** and`text` **templates** to your own phone number.
2. An **unlimited** amount of messages can be sent with the sandbox.
3. Your phone number acts as a **user** and can send and receive messages.
4. The number can be a **landline number**, as long it is able to use WhatsApp.
5. You can switch the **endpoint** at any time. If you don't have one yet you can use a free service like [RequestBin](https://requestbin.com/?gclid=EAIaIQobChMI2bzykoep6gIVkMmyCh2qjguJEAAYASAAEgLY5fD_BwE) to set up an endpoint.
6. Each **Sandbox API Key** is linked to one phone number and you can only send text messages to that phone number. If you wish to test messages with more than 1 number then it is advised to set up a test WhatsApp Business Account (Staging WABA) to use instead of the Sandbox.
   {% endhint %}

{% hint style="danger" %}
**What you cannot do in the Sandbox**

1. The Sandbox is a **test environment** only. You will not be able to use it to send messages to your clients. You can only send messages to your own phone number.
2. **Media** download and upload are not supported yet (coming soon).
3. **Templates** messages can be sent a maximum of 10 times. You can choose between 2 predefined templates.
4. Messages and Templates can be sent only to your own **phone number**.
5. We will only forward and trigger an **API** when your given number is involved.
6. We do not yet provide response information when you use the WhatsApp API.
7. You only have access to the WhatsApp API.
8. Our Sandbox is available to test via the API, but any automated tests would have to be configured from your end.
   {% endhint %}

### **1. Get a Test API Key**

To get a test **`API-KEY`** you can either:

1. Send a WhatsApp message from your phone to the phone number `+4930609859535` **,** with the content **`START`.** Alternatively, you can click this link: <https://wa.me/4930609859535?text=START>.
2. As a response, you will receive your Test **`API-KEY`.** This *key* is associated with your phone's WhatsApp number.
3. Now you are able to use the OneRoute WhatsApp API (Sandbox). You can set your own Webhook or send an unlimited number of messages and limited (10) templates.

### 2. Create your Whatsapp channel (Sandbox) on OneRoute

* Sign in to your OneRoute account.
* Navigate to **Settings** and click [**Channels**](https://app.oneroute.io/settings/channels).

![OneRoute - Add a Channel](/files/hwRgmcAUOqXBTd72fS3q)

* Click **Add an account** in the WhatsApp section(s).
* Select the **Sandbox** option, enter the test **API Key** from **Step 1**, as well as your phone number.
* Click **Verify**.

{% hint style="info" %}
If you entered the correct **phone number** and **API Key**, you would have successfully connected a **Whatsapp** Sandbox channel.
{% endhint %}


# Getting Started

Use OneRoute WhatsApp API in Production

1. Create a [Facebook Business Manager Account](https://business.facebook.com/overview).
2. Create an account with any of our supported Whatsapp 3rd Party Providers - [**360Dialog**](< https://hub.360dialog.com/lp/whatsapp/y8a0kLPA>) **(Preferred)** or [Infobip](https://www.infobip.com/contact).
3. After creating an account, you will be provided with an **`API Key`.** This will be used to set up your OneRoute Whatsapp API in production.

### Connect your WhatsApp channel on OneRoute

* Sign in to your OneRoute account.
* Navigate to **Settings** and click [**Channels**](https://app.oneroute.io/settings/channels).

![OneRoute - Add a Channel](/files/hwRgmcAUOqXBTd72fS3q)

* Click **Add an account** in the WhatsApp section(s).
* Select the **Live** option, and enter the **API Key** gotten from your chosen Whatsapp 3rd party provider.
* Click **Verify**.

{% hint style="info" %}
If you entered the correct **API Key**, you would have successfully connected a **WhatsApp** channel.
{% endhint %}


# Endpoints


# Fetch Channels

## Fetch Whatsapp Channels

<mark style="color:blue;">`GET`</mark> `https://api.oneroute.io/api/public/channels/whatsapp`

This endpoint allows you to fetch Whatsapp channels.

#### Query Parameters

| Name              | Type   | Description                                                          |
| ----------------- | ------ | -------------------------------------------------------------------- |
| name (Optional)   | string | name of the channel to fetch                                         |
| status (Optional) | string | status of the channels to fetch, must be ACTIVE, INACTIVE or PENDING |

#### Headers

| Name   | Type   | Description             |
| ------ | ------ | ----------------------- |
| apiKey | string | API Authentication Key. |

{% tabs %}
{% tab title="200 " %}

```
{
    "data": [
        {
            "id": "8ec725db-7fb8-45db-a7ae-6b3e266f9653",
            "phone": "234XXXXXXXX",
            "identifier": null,
            "medium": "WHATSAPP",
            "credentials": null,
            "description": null,
            "name": "234XXXXXXXX",
            "type": "DEFAULT",
            "country": "NG",
            "status": "ACTIVE",
            "createdAt": "2020-11-09T16:49:40.803Z",
            "updatedAt": "2020-09-11T16:49:40.803Z",
            "firm_id": "e9e46626-0093-4bf6-a657-2a824567d801",
            "provider_config_id": "c9cba1b0-3249-421d-9906-2c99eac972c0"
        },
        {
            "id": "e0c51d87-e22e-4fad-bf05-e848dccdbe37",
            "phone": "234XXXXXXXX",
            "identifier": "234XXXXXXXX",
            "medium": "WHATSAPP",
            "description": "360Dialog Channel",
            "name": "2348178773120",
            "type": "CUSTOM",
            "country": "NG",
            "status": "ACTIVE",
            "createdAt": "2021-06-15T16:18:48.977Z",
            "updatedAt": "2021-06-15T16:34:32.022Z",
            "firm_id": "e9e46626-0093-4bf6-a657-2a824567d801",
            "provider_config_id": "888d7695-0ea8-49b5-a83d-81ce9efeb2c3"
        }
    ],
    "message": "Chanels fetched successfully",
    "success": true
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}


# Fetch Channel Templates

## Fetch WhatsApp Channel Templates

<mark style="color:blue;">`GET`</mark> `https://api.oneroute.io/api/public/channel/:id/templates`

This endpoint allows you to fetch saved templates for a Whatsapp channel.

#### Path Parameters

| Name          | Type   | Description       |
| ------------- | ------ | ----------------- |
| id (Required) | string | id of the channel |

#### Headers

| Name   | Type   | Description                |
| ------ | ------ | -------------------------- |
| apiKey | string | API Key for authentication |

{% tabs %}
{% tab title="200 " %}

```
{
    "body": [
        {
            "category": "ALERT_UPDATE",
            "components": [
                {
                    "example": {
                        "body_text": [
                            [
                                "Michael"
                            ]
                        ]
                    },
                    "text": "Hi {{1}}! We would like to send you a message. Please reply “Yes” if you wish to continue this conversation.",
                    "type": "BODY"
                }
            ],
            "language": "en_GB",
            "name": "new_conversation",
            "namespace": "500jdnc_d0f3_4ds8_ab88_dhndif39993",
            "rejected_reason": null,
            "status": "submitted"
        }
    ],
    "message": "Channel Templates fetched successfully",
    "success": true
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}


# Send Template Message

## Send WhatsApp Template Message

<mark style="color:green;">`POST`</mark> `https://api.oneroute.io/api/public/conversation/template`

Template messages can be delivered at any time. Each template needs to be registered and pre-approved by WhatsApp

#### Headers

| Name   | Type   | Description                 |
| ------ | ------ | --------------------------- |
| apiKey | string | API Key for authentication. |

#### Request Body

| Name                      | Type    | Description                                               |
| ------------------------- | ------- | --------------------------------------------------------- |
| messages.\*.save          | boolean | To save the message as a conversation on OneRoute or not. |
| messages.\*.template      | object  | The template object                                       |
| messages                  | array   | An array of messages to send                              |
| from                      | string  |                                                           |
| messages.\*.to            | string  | Whatsapp number to send template message to.              |
| messages.\*.template.name | string  | the template name                                         |
| messages.\*.metadata      | object  | Pass custom data to the metadata                          |

{% tabs %}
{% tab title="200 " %}

```
{
    "data": [
        {
            "status": "success",
            "response": "gBGHI0kFNWAgTwIJk-_rr1Kse2yO"
        }
    ],
    "message": "Message sent to customer",
    "success": true
}
```

{% endtab %}

{% tab title="400 " %}

```
{
    "data": null,
    "success": false,
    "message": "\"template\" is required"
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}

### Example Request Payload

```
{
    "messages": [
        {
            "template": {
                "name": "first_welcome_messsage",
                "parameters": [
                    {
                        "type": "text",
                        "text": "Michael"
                    }
                ] // leave the array empty if no placeholders in the template
            },
            "metadata": {
                "userId": "..."
            }, // custom properties
            "to": "234XXXXXXXX",
            "save": true
        },
                {
            "template": {
                "name": "new_conversation",
                "parameters": [
                    {
                        "type": "text",
                        "text": "Timothy"
                    }
                ] // leave the array empty if no placeholders in the template
            },
            "metadata": {
                "location": "..."
            }, // custom properties
            "to": "234XXXXXXXX",
            "save": true
        }
    ],
    "from": "234XXXXXXXX"
}
```

### Example Request Payload (Authentication Template)

```
{
    "messages": [
        {
            "template": {
                "name": "first_welcome_messsage",
                "parameters": [
                    {
                        "type": "text",
                        "text": "OTP CODE"
                    }
                ],
                "buttons": [
                    {
                        "type": "text",
                        "text": "OTP CODE"
                    }
                ]
            },
            "metadata": {
                "userId": "..."
            }, // custom properties
            "to": "234XXXXXXXX",
            "save": true
        }
    ],
    "from": "234XXXXXXXX"
}
```


# Send Campaign Message

## Send a WhatsApp Campaign Message

<mark style="color:green;">`POST`</mark> `https://api.oneroute.io/api/public/whatsapp/campaign`

This endpoint is designed for WhatsApp template campaigns with many recipients.&#x20;

Template messages can be delivered at any time. Each template needs to be registered and pre-approved by WhatsApp

We recommend sending the campaign in one request so that it can be grouped else it will be treated as an individual request. All recipients,  corresponding templates, and template parameters are included in an array as shown in the example request payload below

#### Headers

| Name   | Type   | Description                 |
| ------ | ------ | --------------------------- |
| apiKey | string | API Key for authentication. |

#### Request Body

| Name                      | Type    | Description                                               |
| ------------------------- | ------- | --------------------------------------------------------- |
| messages.\*.save          | boolean | To save the message as a conversation on OneRoute or not. |
| messages.\*.template      | object  | The template object                                       |
| messages                  | array   | An array of messages to send                              |
| from                      | string  |                                                           |
| messages.\*.to            | string  | Whatsapp number to send template message to.              |
| messages.\*.template.name | string  | the template name                                         |
| messages.\*.identifier    | string  | a unique id you want give each messages                   |

{% tabs %}
{% tab title="201 " %}

```
{
    "data": {
        "campaign_id": "868a4f7f-3e41-4cd2-aba5-655c8b2ae2bb"
    },
    "message": "Data received",
    "success": true
}
```

{% endtab %}

{% tab title="400 " %}

```
{
    "data": null,
    "success": false,
    "message": "\"template\" is required"
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}

### Example Request Payload

```
{
    "messages": [
        {
            "identifier": "unique_id",
            "template": {
                "name": "first_welcome_messsage",
                "parameters": [
                    {
                        "type": "text",
                        "text": "Michael"
                    }
                ] // leave the array empty if no placeholders in the template
            },
            "to": "234XXXXXXXX",
            "save": true
        },
         {
            "identifier": "unique_id",
            "template": {
                "name": "new_conversation",
                "parameters": [
                    {
                        "type": "text",
                        "text": "Timothy"
                    }
                ] // leave the array empty if no placeholders in the template
            },
            "to": "234XXXXXXXX",
            "save": true
        }
    ],
    "from": "234XXXXXXXX"
}
```

Here is a diagram flow of the lifecycle of a campaign

<figure><img src="/files/mEn3C33L475b4LImxfnh" alt=""><figcaption></figcaption></figure>

To get the status of your campaign, you may call the [logs API](https://docs.oneroute.io/others/fetch-logs),  and pass the campaign ID. A request will also be pushed to your registered webhook upon campaign completion.\
\
You can also get the individual message status by passing the identifier to the url query. You can see more details [here](https://docs.oneroute.io/others/fetch-logs).


# Send Session Message

## Send WhatsApp Session Message

<mark style="color:green;">`POST`</mark> `https://api.oneroute.io/api/public/conversation/text`

This API only works when you have received a Whatsapp message from the customer in the last 24 hours.

#### Headers

| Name   | Type   | Description                 |
| ------ | ------ | --------------------------- |
| apiKey | string | API Key for authentication. |

#### Request Body

| Name    | Type   | Description                                                                       |
| ------- | ------ | --------------------------------------------------------------------------------- |
| from    | string | Whatsapp number you are sending from. Must be connected to a channel on OneRoute. |
| to      | string | Whatsapp number to send the message to. Must be a valid Whatsapp number.          |
| message | string | The message to send to the customer.                                              |

{% tabs %}
{% tab title="200 " %}

```
{
    "data": {
        "id": "c5cb6663-19fb-4551-abee-ddab2d7355d8",
        "content": "Hello :)",
        "contentType": "TEXT",
        "sender": {
            "name": "covid2020",
            "authUser": true,
            "lastActivity": "2021-06-03T14:37:24.684Z"
        },
        "externalId": "gBGHI0kFNWAgTwIJQFXbLV4JUIzD",
        "conversation_id": "65763b7f-b9a1-4370-b2ca-9cacfb0d65c2",
        "updatedAt": "2021-06-03T14:37:25.664Z",
        "createdAt": "2021-06-03T14:37:25.664Z",
        "subject": null,
        "imageUrl": null,
        "videoUrl": null,
        "documentUrl": null,
        "audioUrl": null,
        "quoted_message_id": null
    },
    "message": "Message sent to customer",
    "success": true
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}

### Example Request Payload

```
{
    "from": "234XXXXXXXXXX",
    "message":"Session message",
    "to": "234XXXXXXXXX"
}
```


# FAQ

OneRoute WhatsApp API - Frequently Asked Questions

### 1. What is WhatsApp session messaging?

WhatsApp session ​​messages refer to messages sent and received in response to a message initiated by a user to your business. A messaging session starts when a user sends your business a message and it lasts for a 24 hours window after which you can only send messages to users via template messages to invite them to respond.

### 2. What is WhatsApp template messaging?

Whatsapp template messages refer to pre-approved message templates used for outbound notifications like OTP and appointment reminders. These messages can be delivered at any time to WhatsApp accounts. You must use a WhatsApp Template Message if more than 24 hours have elapsed since the customer last messaged your Whatsapp Business number. WhatsApp templates are charged per message on a pay-as-you-go basis.

### 3. What is the difference between Whatsapp template messaging and Whatsapp session messaging?

Session Messages can only be started by the customer after which, you can receive and send messages freely no rules apply for a 24-hour window. After the 24-hour window has expired, you can send Template Messages that have been paid for only to send notifications or reconnect with customers. Within the 24hours of the session message, you can send and receive messages multiple times with attachments, promotional content, surveys, etc while template messages after the 24-hour window only allows you to send notifications and other approved templates and no promotional or marketing content.


# Getting Started

### Connect your Email Channel to OneRoute

* Sign in to your OneRoute account.
* Navigate to **Settings** and click [**Channels**](https://app.oneroute.io/settings/channels).

![](/files/O1Bg10wosP7R14OG4Os2)

* Click **Add an account** in the Email section.
* Enter email prefix and click **Continue**.
* Setup email sending and forwarding (Optional).


# Endpoints


# Fetch Email Channels

<mark style="color:blue;">`GET`</mark> `https://api.oneroute.io/api/public/channels/email`

#### Query Parameters

| Name              | Type   | Description                                                           |
| ----------------- | ------ | --------------------------------------------------------------------- |
| status (Optional) | String | status of the channels to fetch. Must be ACTIVE , INACTIVE or PENDING |
| name (Optional)   | String | name of the channel to fetch                                          |

#### Headers

| Name                                     | Type   | Description |
| ---------------------------------------- | ------ | ----------- |
| apikey<mark style="color:red;">\*</mark> | String | API key     |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "data": [
        {
            "id": "8d06688b-a050-4c40-89df-9ae0df36cb2c",
            "phone": null,
            "identifier": "support",
            "medium": "EMAIL",
            "credentials": {
                "email": "support@mail.oneroute.io",
                "emailDomain": "mail.oneroute.io"
            },
            "description": "Email Account to Sendgrid",
            "name": "support@mail.oneroute.io",
            "type": "CUSTOM",
            "provider": null,
            "country": "NG",
            "env": "LIVE",
            "status": "ACTIVE",
            "webhookUrl": null,
            "createdAt": "2021-07-16T07:56:41.226Z",
            "updatedAt": "2021-07-16T07:56:41.226Z"
      }
    ],
    "message": "Channels fetched successfully",
    "success": true
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

```javascript
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}


# Send Email to Customers

## Send Email to Customers

<mark style="color:blue;">`GET`</mark> `https://api.oneroute.io/channel/:id/email`

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | String | channel id  |

#### Headers

| Name                                     | Type   | Description |
| ---------------------------------------- | ------ | ----------- |
| apikey<mark style="color:red;">\*</mark> | String | API key     |

#### Request Body

| Name                                         | Type           | Description         |
| -------------------------------------------- | -------------- | ------------------- |
| recipients<mark style="color:red;">\*</mark> | Array\<String> | Email recipients    |
| message<mark style="color:red;">\*</mark>    | Object         | message constructor |
| message.content                              | String         | Email content(Pure  |

{% tabs %}
{% tab title="200: OK Success Response" %}

```javascript
{
    "body": [
        {
            "status": "success",
            "receipent": "test@email.com"
        }
    ],
    "message": "Email processed successfully",
    "success": true
}
```

{% endtab %}
{% endtabs %}


# Getting Started

### Connect your SMS channel on OneRoute

* Sign in to your OneRoute account.
* Navigate to **Settings** and click [**Channels**](https://app.oneroute.io/settings/channels).

![OneRoute - Channels](/files/O1Bg10wosP7R14OG4Os2)

* Click **Add an account** in the SMS section(s).
* Input the SMS **Sender name**.
* Click **Proceed**.


# Endpoints


# Fetch SMS Channels

## Get SMS Channels

<mark style="color:blue;">`GET`</mark> `https://api.oneroute.io/api/public/channels/sms`

#### Query Parameters

| Name              | Type   | Description                                                           |
| ----------------- | ------ | --------------------------------------------------------------------- |
| status (Optional) | string | status of the channels to fetch. Must be ACTIVE , INACTIVE or PENDING |
| name (Optional)   | string | name of the channel to fetch                                          |

#### Headers

| Name                                     | Type   | Description |
| ---------------------------------------- | ------ | ----------- |
| apikey<mark style="color:red;">\*</mark> | string | API key     |

{% tabs %}
{% tab title="200 " %}

```
{
    "data": [
        {
            "id": "553e8ec2-bdc2-4b01-b6bf-eb07fa640218",
            "phone": null,
            "identifier": "OneRoute SMS",
            "medium": "SMS",
            "credentials": null,
            "description": "SMS Channel",
            "name": "OneRoute SMS",
            "type": "CUSTOM",
            "country": "NG",
            "status": "ACTIVE",
            "createdAt": "2021-08-04T12:32:11.543Z",
            "updatedAt": "2021-08-04T12:32:11.543Z",
            "firm_id": "e9e46626-0093-4bf6-a657-2a824567d801",
            "provider_config_id": "d2fd2feb-06dc-4787-ae3e-dbeb20e184d2"
        }
    ],
    "message": "Chanels fetched successfully",
    "success": true
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}


# Send SMS to Customers

## Send SMS to Customers

<mark style="color:green;">`POST`</mark> `https://api.oneroute.io/api/public/channel/:id/sms`

#### Path Parameters

| Name                                 | Type   | Description       |
| ------------------------------------ | ------ | ----------------- |
| id<mark style="color:red;">\*</mark> | string | id of the channel |

#### Headers

| Name                                     | Type   | Description                 |
| ---------------------------------------- | ------ | --------------------------- |
| apiKey<mark style="color:red;">\*</mark> | string | API key for authentication. |

#### Request Body

| Name          | Type   | Description                                                                         |
| ------------- | ------ | ----------------------------------------------------------------------------------- |
| message       | string | The message to send to the customers                                                |
| recipients    | array  | List of recipients phone numbers                                                    |
| recipients.\* | string | recipient phone number. Must be in international format (Example: `2341793026727`). |

### Request Payload

```json
{
    "message": "message content",
    "recipients": ["23490xxxxxxxx"]
}
```

### Response

{% tabs %}
{% tab title="200" %}

```json
{
    "body": [
        {
            "status": "success",
            "response": "4744271336207951463605"
        }
    ],
    "message": "SMS processed successfully",
    "success": true
}
```

{% endtab %}
{% endtabs %}


# Send OTP SMS to Customers

## Send OTP SMS to Customers

<mark style="color:green;">`POST`</mark> `https://api.oneroute.io/api/public/sms`

This is for sending OTP messages only

#### Headers

| Name                                     | Type   | Description                 |
| ---------------------------------------- | ------ | --------------------------- |
| apiKey<mark style="color:red;">\*</mark> | string | API key for authentication. |

#### Request Body

| Name          | Type   | Description                                                                         |
| ------------- | ------ | ----------------------------------------------------------------------------------- |
| message       | string | The message to send to the customers                                                |
| recipients    | array  | List of recipients phone numbers                                                    |
| recipients.\* | string | recipient phone number. Must be in international format (Example: `2341793026727`). |

### Request Payload

```json
{
    "message": "message content",
    "recipients": ["23490xxxxxxxx"]
}
```

### Response

{% tabs %}
{% tab title="200 " %}

```json
{
    "body": [
        {
            "status": "success",
            "response": "4744271336207951463605"
        }
    ],
    "message": "SMS processed successfully",
    "success": true
}
```

{% endtab %}
{% endtabs %}


# Fetch SMS Messages

<mark style="color:blue;">`GET`</mark> `https://api.oneroute.io/api/public/channel/id/sms`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | String | channel id  |

#### Query Parameters

| Name                                            | Type   | Description                                                                 |
| ----------------------------------------------- | ------ | --------------------------------------------------------------------------- |
| status (Optional)                               | String | status of the messages to fetch. Must be delivered, pending or undelivered. |
| page\[size]<mark style="color:red;">\*</mark>   | String | the limit of messages per page                                              |
| page\[number]<mark style="color:red;">\*</mark> | String | page to load e.g 1, 2                                                       |

#### Headers

| Name                                     | Type   | Description |
| ---------------------------------------- | ------ | ----------- |
| apikey<mark style="color:red;">\*</mark> | String | API key     |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "data": [
        {
            "id": "8d06688b-a050-4c40-89df-9ae0df36cb2c",
            "phone": null,
            "identifier": "support",
            "medium": "EMAIL",
            "credentials": {
                "email": "support@mail.oneroute.io",
                "emailDomain": "mail.oneroute.io"
            },
            "description": "Email Account to Sendgrid",
            "name": "support@mail.oneroute.io",
            "type": "CUSTOM",
            "provider": null,
            "country": "NG",
            "env": "LIVE",
            "status": "ACTIVE",
            "webhookUrl": null,
            "createdAt": "2021-07-16T07:56:41.226Z",
            "updatedAt": "2021-07-16T07:56:41.226Z"
      }
    ],
    "message": "Channels fetched successfully",
    "success": true
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

```javascript
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}


# Get SMS DLR Message

<mark style="color:blue;">`GET`</mark> `https://api.oneroute.io/api/public/dlr/id/sms`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | String | message id  |

#### Headers

| Name                                     | Type   | Description |
| ---------------------------------------- | ------ | ----------- |
| apikey<mark style="color:red;">\*</mark> | String | API key     |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "event": "smsDeliveryReport",
    "message": null,
    "conversation": {
        "id": "1234567",
        "externalId": "1234567890",
        "status": "delivered",
        "reason": "Message delivered to handset",
        "from": "Name",
        "to": "12345678",
        "units": 0,
        "delivered_time": "2023-08-29T08:18:31.732Z",
        "createdAt": "2023-08-29T08:18:28.576Z"
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

```javascript
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}


# Getting Started

OneOTP is an API that enables you to send One-Time Passwords via SMS, Whatsapp, Email, and USSD to your customers. This can be used for phone number/email verification during sign-up / onboarding, password resets, and securing transactions.


# Endpoints


# Fetch OTP Templates

## Fetch OTP Templates

<mark style="color:blue;">`GET`</mark> `https://api.oneroute.io/api/oneotp/templates`

With this endpoint, you can choose from a list of OTP templates and retrieve the ID of the template you wish to send to the customer.

#### Headers

| Name   | Type   | Description                 |
| ------ | ------ | --------------------------- |
| apikey | string | API key for Authentication. |

{% tabs %}
{% tab title="200 OneOTP Templates fetched successfully." %}

```
{
    "body": [
        {
            "id": "86681a74-ecdb-4492-9e75-93dadb9f8a29",
            "body": "Your {{firm}} OTP code is {{otp}}.",
            "name": "otp_template_simple",
            "namespace": "5000f34c_d9ab_4fd8_aa48_d9091f1d21ff",
            "data": [],
            "locale": "en",
            "policy": "DETERMINISTIC",
            "status": "approved",
            "type": "text",
            "scope": "oneOTP",
            "createdAt": "2021-10-02T14:00:29.937Z",
            "updatedAt": "2021-10-02T14:00:29.937Z",
            "firm_id": null
        },
        {
            "id": "ad90555b-46fa-433c-a350-9cc8911b4362",
            "body": "Your One Time Password (OTP) for {{firm}} is {{otp}}. Do not share your OTP with anyone.",
            "name": "otp_template",
            "namespace": "5000f34c_d9ab_4fd8_aa48_d9091f1d21ff",
            "data": [],
            "locale": "en_GB",
            "policy": "DETERMINISTIC",
            "status": "approved",
            "type": "text",
            "scope": "oneOTP",
            "createdAt": "2021-10-02T14:00:29.937Z",
            "updatedAt": "2021-10-02T14:00:29.937Z",
            "firm_id": null
        },
        {
            "id": "63d45b42-0898-43b3-b81d-1fb2d45bc78f",
            "body": "Your One Time Password (OTP) for {{firm}} is {{otp}}. Do not share your OTP with anyone. This code will expire in {{minutes}} minutes.",
            "name": "otp_template_expiry",
            "namespace": "5000f34c_d9ab_4fd8_aa48_d9091f1d21ff",
            "data": [],
            "locale": "en",
            "policy": "DETERMINISTIC",
            "status": "approved",
            "type": "text",
            "scope": "oneOTP",
            "createdAt": "2021-10-02T14:00:29.937Z",
            "updatedAt": "2021-10-02T14:00:29.937Z",
            "firm_id": null
        }
    ],
    "message": "OneOTP Templates fetched successfully",
    "success": true
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}


# Send OTP

## Send OTP

<mark style="color:green;">`POST`</mark> `https://api.oneroute.io/api/oneotp/send`

Send OTPs to customers with this endpoint. Provide the template, channels, recipient and indicate whether you'd like to generate your OTP or use the generated OTP.&#x20;

#### Headers

| Name   | Type   | Description                 |
| ------ | ------ | --------------------------- |
| apikey | string | API Key for Authentication. |

#### Request Body

| Name                 | Type    | Description                                                                                                   |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| channels             | array   | A list of channels to send the OTP to. Allowed values are "WHATSAPP", "EMAILS", "SMS" and "USSD"              |
| templateId           | string  | OTP Template to send to customer.                                                                             |
| email                | string  | Email to send OTP to, if EMAIL channel is selected.                                                           |
| options.otp          | string  | OTP to use, overwrites the generated OTP.                                                                     |
| options.length       | number  | Length of generated OTP. Defaults to 4                                                                        |
| options.digits       | boolean | If generated OTP should contain digits. Defaults to true.                                                     |
| options.alphabets    | boolean | If generated OTP should contain alphabets. Defaults to false                                                  |
| options.upperCase    | boolean | If generated OTP should contain upperCase letters. Defaults to false.                                         |
| options.specialChars | boolean | If generated OTP should contain special characters. Defaults to false                                         |
| options.minutes      | number  | Number of minutes the OTP should last. Defaults to 5 minutes.                                                 |
| phoneNumber          | string  | <p>The phone number to send WHATSAPP,  SMS or USSD to.<br>Required if any of those channels are selected.</p> |

{% tabs %}
{% tab title="200 " %}

```
{
    "body": {
        "key": "B2LN36qdsQ3x1PK6mpcbOjz8IBpskZtWbxPJqmKULX4tRDy4dZsBr9pXX2tEjyk5+dDGtKJvzYFS0C9BaUbXGGJ5SknlDLNa+S5AerAcXeCgdDqC37IoRJ6xzDrJhAfuySqJkYrNDC2rz+bTztC2hJFjN7YxikLt2XOv14qQMgeGCBG8sTqtJqaAz9eAFCKKks6u3bbLbWGO68JKF/SInMEuMDvAhyD/EE8k86xJCCkzp0LnILlXUi9d6XzieuBKk8xIVv5+aHQ3VRhnmahkxA==",
        "data": [
            {
                "medium": "WHATSAPP",
                "data": "gBGHI0kFNWAgTwIJqUIvBBh1yT38"
            },
            {
                "medium": "SMS",
                "data": "33333530654203571912"
            },
            {
                "medium": "EMAIL",
                "data": "Sent successfully"
            }
        ],
        "errors": []
    },
    "message": "Otp sent successfully",
    "success": true
}
```

{% endtab %}

{% tab title="400 " %}

```
{
    "message": "Unable to process your request",
    "errors": [
        {
            "medium": "WHATSAPP",
            "error": "Invalid Whatsapp Number"
        }
    ],
    "success": false
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}

### Example Request Payload

```
{
    "channels": ["WHATSAPP", "SMS", "EMAIL"],
    "phoneNumber": "+2349XXXXXXXX",
    "templateId": "63d45b42-0898-43b3-b81d-1fb2d45bc78f",
    "options": {
        "length": 6,
        "digits": true,
        "alphabets": false,
        "minutes": 10
    },
    "email": "email@example.com"
}
```


# Verify OTP

## Verify OTP

<mark style="color:green;">`POST`</mark> `https://api.oneroute.io/api/oneotp/verify`

Use this endpoint to verify that the customer entered the same OTP that was sent with the Send OTP endpoint.&#x20;

#### Headers

| Name   | Type   | Description                  |
| ------ | ------ | ---------------------------- |
| apikey | string | API key, for Authentication. |

#### Request Body

| Name       | Type   | Description                                  |
| ---------- | ------ | -------------------------------------------- |
| key        | string | Verification Key, from the Send OTP request. |
| otp        | string | OTP to verify                                |
| identifier | string | email or phone number the OTP was sent to    |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "Otp verified successfully",
    "body": {
        "status": "Success",
        "response": "OTP Matched"
    },
    "success": true
}
```

{% endtab %}

{% tab title="400 " %}

```
{
    "data": null,
    "message": "OTP already used!!",
    "success": false
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}

### **Verify with USSD**

When you include USSD as one of your preferred OneOTP channels, your customers can verify their OTP by dialing your USSD code which you can find on your [Account Settings Page](https://app.oneroute.io/settings/account-settings).

Once verification is complete, a notification will be sent to the `webhook url`configured on your [Account Settings Page](https://app.oneroute.io/settings/account-settings) to notify you that the OTP has been verified successfully.

#### Webhook Payload Sample

```
{
    "id": "63d45b42-0898-43b3-b81d-1fb2d45bc78f",
    "otp": "1234",
    "identifier": "+234XXXXXXXX",
    "expiration_time": "1941-06-22T16:36:45.742Z"
    "createdAt": "1941-06-22T16:36:45.742Z"
}
```


# Getting Started

OneRoute Embed is the fastest way to integrate business communication features into your application. Our SDKs and APIs enable you to grant your business customers the ability to communicate with their customers directly from your application.&#x20;


# Installation

We support two different ways to install OneRoute Embed on your website. The first is a [standard installation](#standard-installation) and will work for most websites. The second is for a [single-page app](#single-page-app).

{% hint style="info" %}
First, you need to ensure that you are on a Business plan to use this.
{% endhint %}

### Standard Installation

If you have a web app with multiple pages where each one triggers a new page refresh then you will most likely need the basic JavaScript method. This means you will not need to create separate actions that trigger when the Embed will appear. The page refresh itself is enough to trigger the action. To set up the basic JavaScript, you will only need to follow these steps.

#### How to Install <a href="#how-to-install" id="how-to-install"></a>

To get the Embed to appear on your web app, you need to set the element you want it to show within.

```
<div id="onerouteEmbed"></div>
```

Then, copy and paste the snippet below before the `</body>` tag.

```
<script>
  const orEmbedConfig = {
    api_key: "API_KEY",
    firm_id: "FIRM_ID",
    business_name: user.business.name, //User's business name
    business_id: user.business.id, //User's business id
    user_first_name: user.firstname,
    user_last_name: user.lastname,
    user_email: user.email,
    
    // Optional keys
    style: {"primary_color": "#FF33F0"},
  };

  function loadOneRouteEmbed() {
    const orEmbedEl = document.getElementById("onerouteEmbed");
    if (orEmbedEl) {
      orEmbedEl.className = "oneroute_embed";
      orEmbedEl.setAttribute("data-config", JSON.stringify(orEmbedConfig));
    
      const scriptElement = document.createElement("script");
      scriptElement.src = "https://rebrand.ly/or-embed";
      document.body.appendChild(scriptElement);
    }
  }
  loadOneRouteEmbed();
</script>
```

You can find your API\_KEY and FIRM\_ID on your *OneRoute Dashboard* > *Settings* > [*Account Settings*](https://app.oneroute.io/settings/account-settings) > *API Keys & Webhooks*.

### Single Page App

If you have a single-page app, then you can get OneRoute Embed installed on your page. So let's waste no time and get you chatting with your customers.

#### How to Install <a href="#how-to-install" id="how-to-install"></a>

To get the Embed to appear on your web app, you need to set the element on the page/component you want it to show within.

```
<div id="onerouteEmbed"></div>
```

Then, copy and paste the snippet below into the page on-mount function (useEffect, componentDidMount, ngAfterViewInit, mounted, etc).

```
const orEmbedConfig = {
  api_key: "API_KEY",
  firm_id: "FIRM_ID",
  business_name: user.business.name, //User's business name
  business_id: user.business.id, //User's business id
  user_first_name: user.firstname,
  user_last_name: user.lastname,
  user_email: user.email,
    
  // Optional keys
  style: {"primary_color": "#FF33F0"},
};

function loadOneRouteEmbed() {
  const orEmbedEl = document.getElementById("onerouteEmbed");
  if (orEmbedEl) {
    orEmbedEl.className = "oneroute_embed";
    orEmbedEl.setAttribute("data-config", JSON.stringify(orEmbedConfig));
    
    const scriptElement = document.createElement("script");
    scriptElement.src = "https://rebrand.ly/or-embed";
    document.body.appendChild(scriptElement);
  }
}
loadOneRouteEmbed();
```

You can find your API\_KEY and FIRM\_ID on your *OneRoute Dashboard* > *Settings* > [*Account Settings*](https://app.oneroute.io/settings/account-settings) > *API Keys & Webhooks*.

This is an example of how it'll look after a successful installation.

<figure><img src="/files/TPVkiEiHtEsdPX8PaUwv" alt=""><figcaption><p>OneRoute Embed</p></figcaption></figure>


# Push Notification

OneRoute Embed also supports push notifications and requires some dependencies from your Web App.

#### How to Install <a href="#how-to-install" id="how-to-install"></a>

* Create a `firebase-messaging-sw.js` file in your public folder (make sure to use the exact filename).
* Copy and paste the code below in the file created:

```
/* eslint-disable no-restricted-globals */
/* eslint-disable no-undef */

importScripts(
  "https://www.gstatic.com/firebasejs/9.0.0/firebase-app-compat.js"
);
importScripts(
  "https://www.gstatic.com/firebasejs/9.0.0/firebase-messaging-compat.js"
);

const firebaseConfig = {
  apiKey: "<-- Check dashboard -->",
  authDomain: "<-- Check dashboard -->",
  projectId: "<-- Check dashboard -->",
  storageBucket: "<-- Check dashboard -->",
  messagingSenderId: "<-- Check dashboard -->",
  appId: "<-- Check dashboard -->",
};

firebase.initializeApp(firebaseConfig);

// Retrieve firebase messaging
const messaging = firebase.messaging();

messaging.onBackgroundMessage(function (payload) {
  const message = JSON.parse(payload.data.message);
  console.log("NBMA");

  const notificationTitle = `New message from ${message.sender.name}`;
  const notificationOptions = {
    body: message.content,
    icon: "/favicon.ico", // Your WebApp's favicon.
  };

  self.registration.showNotification(notificationTitle, notificationOptions);
  self.addEventListener("notificationclick", function (event) {
    event.notification.close();
  });
});

```

You can find the values for the `firebaseConfig` keys on your *OneRoute Dashboard* > *Settings* > [*Account Settings*](https://app.oneroute.io/settings/account-settings) > *Notifications*.

* Redeploy your WebApp, and you should start getting push notifications.


# Receiving Events - Webhooks

When new messages come into any of your channels or you want to be notified immediately we have any updates on your conversations, we trigger events that your application can listen to. We do this using webhooks.

A webhook is a URL on your server where we send payloads for such events.

You can specify your webhook URL on your [Settings page](https://app.oneroute.io/settings/account-settings) or on individual channels where we would send `POST` requests to whenever an event occurs.

{% hint style="info" %}
Kindly ensure your webhook URL is publicly available (localhost URLs cannot receive events).
{% endhint %}

### Verify Event Origin

#### Signature

Our event comes with \`\`\`x-oneroute-signature\`\`\` in the header and you can use this to verify the event is from us and wasn't tampered with. To verify the origin, you can use the below code

```
const oneRouteSignatureHash = req.headers['x-oneroute-signature']
const hash = crypto.createHmac('sha512', 'OneRoute Secret Key').update(JSON.stringify(req.body)).digest('hex');

if (oneRouteSignatureHash === hash) {
    // valid... do something
} else {
    // invalid...  do something
}
```

#### IP whitelisting <a href="#ip-whitelisting" id="ip-whitelisting"></a>

With this method, you only allow certain IP addresses to access your webhook URL while blocking out others. OneRoute will only send webhooks from the following IP addresses:

1. 174.138.104.128

### Receiving Events

To receive the event, you will have to create an unauthenticated `POST` route on your application that returns a <mark style="color:green;background-color:blue;">`200`</mark> status code as it's response.

{% tabs %}
{% tab title="Node" %}

```
// Using Express
app.post("/my/webhook/url", function(req, res) {
    // Retrieve the request's body
    var event = req.body;
    // Do something with event
    res.send(200);
});
```

{% endtab %}

{% tab title="PHP" %}

```
<?php
// Retrieve the request's body and parse it as JSON
$input = @file_get_contents("php://input");
$event = json_decode($input);
// Do something with $event
http_response_code(200); // PHP 5.4 or greater
?>
```

{% endtab %}
{% endtabs %}

### Supported Events

{% tabs %}
{% tab title="New Incoming Message" %}

```json
{
  "event": "newMessage",
  "message": {
    "sender": {
      "name": "Message Sender",
      "authUser": false,
      "lastActivity": "2022-01-29T07:27:52.676Z"
    },
    "externalId": null,
    "content": "Hello World!",
    "contentType": "TEXT",
    "imageUrl": null,
    "videoUrl": null,
    "documentUrl": null,
    "audioUrl": null,
    "quoted_message_id": null,
    "conversation_id": "bf9d96d9-e495-489a-a22a-206b0ea44d90"
  },
  "conversation": {
    "id": "bf9d96d9-e495-489a-a22a-206b0ea44d90",
    "subject": null,
    "agent": null,
    "customer": {
      "name": "Customer name",
      "email": "customer@mail.com"
    },
    "lastMessageAt": "2022-01-29T07:27:52.793Z",
    "status": "in-queue",
    "country": "NG",
    "read": false,
    "createdAt": "2022-01-29T07:18:58.172Z",
    "updatedAt": "2022-01-29T07:27:52.794Z",
    "agent_id": null,
    "Channel": {
      "id": "8bad2edc-2973-4cec-8f33-a17c54dc0686",
      "phone": null,
      "identifier": "Identifier",
      "medium": "WHATSAPP",
      "credentials": null,
      "description": "Whatsapp Channel",
      "name": "Channel name",
      "type": "CUSTOM",
      "provider": null,
      "country": "NG",
      "env": "LIVE",
      "status": "ACTIVE",
      "webhookUrl": "https://webhook.url"
    }
  }
}
```

{% endtab %}

{% tab title="Low Balance Notification" %}

```json
{
    "event": "lowUnitBalance",
    "firm": "Firm Name",
    "units": 0 // remaining unit balance
}
```

{% endtab %}

{% tab title="OTP Verified" %}

```json
{
    "event": "otpVerified",
    "id": "12345678904",
    "otp": "12345",
    "identifier": "key",
    "expiration_time": "2022-01-29T07:27:52.676Z",
    "createdAt": "2022-01-22T07:27:52.676Z",
    "verified": true
}
```

{% endtab %}

{% tab title="SMS Delivery Report" %}

```json
{
    "event": "smsDeliveryReport",
    "message": null,
    "conversation": {
        "id": "1234567",
        "externalId": "1234567890",
        "status": "delivered",
        "reason": "Message delivered to handset",
        "from": "Name",
        "to": "12345678",
        "units": 0,
        "delivered_time": "2023-08-29T08:18:31.732Z",
        "createdAt": "2023-08-29T08:18:28.576Z"
    }
}
```

{% endtab %}

{% tab title="Whatsapp Delivery Report" %}

```json
{
    "event": "whatsappDeliveryReport",
    "message": null,
    "conversation": {
        "id": "iodsjiohsduihys7ywwy8oisd",
        "externalId": "iusdiywy78wt6stfauahiu",
        "status": "read",
        "reason": null,
        "from": "23480xxxxxxxx",
        "to": "+23480xxxxxxxx",
        "units": 0,
        "delivered_time": "2024-12-04T13:49:05.000Z",
        "template_category": "MARKETING",
        "createdAt": "2024-12-04T13:47:23.000Z",
        "campaign_id": null,
        "identifier": null
    }
}
```

{% endtab %}
{% endtabs %}

### WhatsApp Campaign Events

{% tabs %}
{% tab title="Campaign Completed " %}

```json
{
    "event": "compaignDeliveryReport",
    "message": "campaign completed.",
    "campaignReportUrl": "https://api.oneroute.io/api/public/logs?page[size]=10&page[number]=1&campaign_id=campaign_id"
    "conversation": {
        "id": "id",
        "firm_id": "firm id"
    }
}
```

{% endtab %}

{% tab title="Campaign Message DLR" %}

```json
{
    "event": "whatsappDeliveryReport",
    "message": null,
    "conversation": {
        "id": "iodsjiohsduihys7ywwy8oisd",
        "externalId": "iusdiywy78wt6stfauahiu",
        "status": "read",
        "reason": null,
        "from": "234879927352",
        "to": "+23480634279362",
        "units": 0,
        "delivered_time": "2024-12-04T13:49:05.000Z",
        "template_category": "MARKETING",
        "createdAt": "2024-12-04T13:47:23.000Z",
        "campaign_id": "982376327jiadnkjddxtdd",
        "identifier": "f1005383-7d8d-4351"
    }
}
```

{% endtab %}

{% tab title="Campaign Report Sample" %}

```json
{
    "count": 2,
    "data": [
        {
            "id": "uiwyytw8728928ujd",
            "externalId": "isjdoijui87w6e7iousiojiosdus",
            "status": "read",
            "reason": null,
            "from": "2348183625392",
            "to": "+234808376725898",
            "units": 0,
            "delivered_time": "2024-12-04T13:49:05.000Z",
            "createdAt": "2024-12-04T13:47:23.000Z",
            "campaign_id": "8932789ujksdmkiosuydw78",
            "identifier": "f1005383-7d8d-4351"
        },
        ...
    ],
    "currentPage": 1,
    "totalPage": 1,
    "message": "logs data",
    "success": true
}
```

{% endtab %}
{% endtabs %}


# Fetch Channel By Id

## Get Channel By Id

<mark style="color:blue;">`GET`</mark> `https://api.oneroute.io/api/public/channel/:id`

This endpoint allows you to fetch a channel by its ID.

#### Path Parameters

| Name | Type   | Description                 |
| ---- | ------ | --------------------------- |
| id   | string | id of the channel to fetch. |

#### Headers

| Name   | Type   | Description                 |
| ------ | ------ | --------------------------- |
| apiKey | string | API Key for authentication. |

{% tabs %}
{% tab title="200 " %}

```
{
    "data": {
        "id": "553e8ec2-bdc2-4b01-b6bf-eb07fa640218",
        "phone": null,
        "identifier": "OneRoute SMS",
        "medium": "SMS",
        "credentials": null,
        "description": "SMS Channel",
        "name": "OneRoute SMS",
        "type": "CUSTOM",
        "country": "NG",
        "status": "ACTIVE",
        "createdAt": "2021-08-04T12:32:11.543Z",
        "updatedAt": "2021-08-04T12:32:11.543Z",
        "firm_id": "e9e46626-0093-4bf6-a657-2a824567d801",
        "provider_config_id": "d2fd2feb-06dc-4787-ae3e-dbeb20e184d2"
    },
    "message": "channel fetched successfully",
    "success": true
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}

{% tab title="404 " %}

```
{
    "data": null,
    "message": "channel not found",
    "success": false
}
```

{% endtab %}
{% endtabs %}


# Fetch Logs

## Get Logs

<mark style="color:blue;">`GET`</mark> `https://api.oneroute.io/api/public`/logs?page\[size]=10\&page\[number]=1

This endpoint allows you to fetch logs

#### Query Parameters

<table><thead><tr><th>Name</th><th>Type</th><th>Description</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td>page[size]</td><td>number</td><td>page limit</td><td>true</td></tr><tr><td>page[number]</td><td>number</td><td>page number</td><td>true</td></tr><tr><td>id</td><td>string</td><td>id of the log</td><td>false</td></tr><tr><td>campaign_id</td><td>string</td><td>campaign id</td><td>false</td></tr><tr><td>identifier</td><td>string</td><td>identifier</td><td>false</td></tr></tbody></table>

#### Headers

| Name   | Type   | Description                 |
| ------ | ------ | --------------------------- |
| apiKey | string | API Key for authentication. |

{% tabs %}
{% tab title="200 " %}

````json
```json
{
    "count": 7,
    "data": [
        {
            "id": "acebf1b3-4df0-408b-971d-b533296ff0e6",
            "externalId": "123488990267",
            "status": "delivered",
            "reason": null,
            "from": "234790097862",
            "to": "+2348752653027",
            "units": 0,
            "delivered_time": null,
            "createdAt": "2024-11-04T16:01:57.385Z",
            "campaign_id": "f1005383-7d8d-4351-b3cb-f0063ce10557",
            "identifier": "f1005383-7d8d-4351"
        }
    ],
    "currentPage": 1,
    "totalPage": 1,
    "message": "logs data",
    "success": true
}
```
````

{% endtab %}

{% tab title="401 " %}

```
{
    "data": null,
    "message": "Invalid API Key",
    "success": false
}
```

{% endtab %}
{% endtabs %}