# Lipachat Docs

Welcome to the Lipachat API documentation! Lipachat offers powerful WhatsApp APIs that enable you to easily send and receive messages, media, and more through WhatsApp. Whether you're looking to integrate real-time communication or automate responses, our APIs provide everything you need to interact with WhatsApp at scale.

Explore our documentation to learn how to get started, implement different messaging features, and make the most out of Lipachat’s solutions.

### Jump right in

<table data-view="cards"><thead><tr><th data-type="files"></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td></td><td><strong>Onboarding</strong><br>Sign up to our platform</td><td><a href="/files/6x91o6SypGIfo9JYl0yj">/files/6x91o6SypGIfo9JYl0yj</a></td><td></td><td><a href="/pages/CyH2xJQs9yWJ1S8BYNav">/pages/CyH2xJQs9yWJ1S8BYNav</a></td></tr><tr><td></td><td><p><strong>Templates</strong></p><p>Create and Send Templates</p></td><td><a href="/files/0Nljd4wPBpt1zDIBJlmr">/files/0Nljd4wPBpt1zDIBJlmr</a></td><td></td><td><a href="/pages/i25u7r2AFJYqtiFdRcoY">/pages/i25u7r2AFJYqtiFdRcoY</a></td></tr><tr><td></td><td><strong>Free Form Messages</strong><br>Send Free form messages</td><td><a href="/files/xC0C1rwoSiDes8zXWEtP">/files/xC0C1rwoSiDes8zXWEtP</a></td><td></td><td><a href="/pages/cEHgDv7NGBquDGHeLyQ4">/pages/cEHgDv7NGBquDGHeLyQ4</a></td></tr><tr><td></td><td><strong>Send media</strong><br>Send images, videos and documents.<br></td><td><a href="/files/CWairP5Mh4Gs7O1BhP5q">/files/CWairP5Mh4Gs7O1BhP5q</a></td><td></td><td><a href="/pages/JjjojIyKxaiBPzzLwvtg">/pages/JjjojIyKxaiBPzzLwvtg</a></td></tr><tr><td></td><td><strong>Webhooks</strong><br>Receiving messages and media.</td><td><a href="/files/LDU3xoFmJilTLehQfNY5">/files/LDU3xoFmJilTLehQfNY5</a></td><td></td><td></td></tr><tr><td></td><td></td><td></td><td></td><td></td></tr></tbody></table>


# Getting Started with Lipachat

Lipachat enables you to easily integrate WhatsApp APIs into your applications to send and receive messages from your customers, helping you enhance communication and engagement.

{% stepper %}
{% step %}

#### Sign Up for the Sandbox Environment

To get started, [sign up](https://app.lipachat.com) for our sandbox environment, where you can quickly test your integrations before going live.
{% endstep %}

{% step %}

#### Test with Lipachat’s Sandbox Number

For testing purposes, we provide a sandbox number: **+254110090747**. You can use this number to quickly experiment with the APIs and simulate real-world WhatsApp interactions.

[Read more..](/reference/sandbox)
{% endstep %}

{% step %}

### Link Your Number

Reference the guide [here](/reference/go-live) to learn how to go live with your number.
{% endstep %}
{% endstepper %}

### 📘 Quick Tutorials

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>Build A Chat Bot</strong></td><td></td><td><a href="/pages/jO3wQQXUVqFGje4YxJlS">/pages/jO3wQQXUVqFGje4YxJlS</a></td><td><a href="/files/6A8tVe7dqWyEDOuIVayk">/files/6A8tVe7dqWyEDOuIVayk</a></td></tr><tr><td><strong>CRM Workflow</strong></td><td></td><td><a href="/pages/ZikgGjEhJkhoBo5nHuC7">/pages/ZikgGjEhJkhoBo5nHuC7</a></td><td><a href="/files/DQck5SPE5VIbxTxz1gJL">/files/DQck5SPE5VIbxTxz1gJL</a></td></tr><tr><td><strong>Broadcast Messages</strong></td><td></td><td><a href="/pages/5aZvF823bnE9Wk7fguLU">/pages/5aZvF823bnE9Wk7fguLU</a></td><td><a href="/files/E91AkzwgXCZ8ym00kc8S">/files/E91AkzwgXCZ8ym00kc8S</a></td></tr></tbody></table>

[![Run In Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/1880882-362c9de0-8bff-4dbb-9596-194223a41ad8?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D1880882-362c9de0-8bff-4dbb-9596-194223a41ad8%26entityType%3Dcollection%26workspaceId%3D22009359-4643-460b-b79e-d2fed7c4e868#?env%5BLipachatWhatsappAPI%5D=W3sia2V5IjoiV0FfUEhPTkVfTlVNQkVSIiwidmFsdWUiOiIyNTQxMTAwOTA3NDciLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6IjI1NDExMDA5MDc0NyIsImNvbXBsZXRlU2Vzc2lvblZhbHVlIjoiMjU0MTEwMDkwNzQ3Iiwic2Vzc2lvbkluZGV4IjowfSx7ImtleSI6ImFwaUtleSIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQiLCJzZXNzaW9uVmFsdWUiOiIiLCJjb21wbGV0ZVNlc3Npb25WYWx1ZSI6IiIsInNlc3Npb25JbmRleCI6MX0seyJrZXkiOiJZT1VSX1BIT05FX05VTUJFUiIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQiLCJzZXNzaW9uVmFsdWUiOiIiLCJjb21wbGV0ZVNlc3Npb25WYWx1ZSI6IiIsInNlc3Npb25JbmRleCI6Mn1d)


# Templates

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td></td><td>Introduction</td><td></td><td><a href="https://images.unsplash.com/photo-1530435460869-d13625c69bbf?crop=entropy&#x26;cs=srgb&#x26;fm=jpg&#x26;ixid=M3wxOTcwMjR8MHwxfHNlYXJjaHwxfHx0ZW1wbGF0ZXN8ZW58MHx8fHwxNzYzNDYzNTE5fDA&#x26;ixlib=rb-4.1.0&#x26;q=85">https://images.unsplash.com/photo-1530435460869-d13625c69bbf?crop=entropy&#x26;cs=srgb&#x26;fm=jpg&#x26;ixid=M3wxOTcwMjR8MHwxfHNlYXJjaHwxfHx0ZW1wbGF0ZXN8ZW58MHx8fHwxNzYzNDYzNTE5fDA&#x26;ixlib=rb-4.1.0&#x26;q=85</a></td><td><a href="/pages/DTJwRGthRrPHPbMvEyI7">/pages/DTJwRGthRrPHPbMvEyI7</a></td></tr><tr><td></td><td>Creating Templates</td><td></td><td><a href="/files/2si0vhrybbavL9ZJVzBC">/files/2si0vhrybbavL9ZJVzBC</a></td><td><a href="/pages/DHsCy3cbKhE9qroXyUTY">/pages/DHsCy3cbKhE9qroXyUTY</a></td></tr><tr><td></td><td>Updating Templates</td><td></td><td><a href="/files/YC8BTkZpyGOjKVsbCJoe">/files/YC8BTkZpyGOjKVsbCJoe</a></td><td><a href="/pages/Eb4qEo713oS0aiArJaAW">/pages/Eb4qEo713oS0aiArJaAW</a></td></tr><tr><td></td><td>Listing created templates</td><td></td><td><a href="/files/aZOlZ5Foew3QKf3S8mWx">/files/aZOlZ5Foew3QKf3S8mWx</a></td><td><a href="/pages/NCQ7sOZ9ak3bVfzYNNfj">/pages/NCQ7sOZ9ak3bVfzYNNfj</a></td></tr><tr><td></td><td>Sending Templates</td><td></td><td><a href="/files/E91AkzwgXCZ8ym00kc8S">/files/E91AkzwgXCZ8ym00kc8S</a></td><td><a href="/pages/rAVLSB5jpMBRzcrBWIDk">/pages/rAVLSB5jpMBRzcrBWIDk</a></td></tr></tbody></table>


# Intro

Overview

WhatsApp requires *message templates* for any business-initiated communication that occurs outside of an active session. A *session* automatically begins whenever a user sends a message to your WhatsApp number and remains open for 24 hours. During an active session, you can exchange free-form messages without additional constraints.

***

When to Use a Message Template

1. **Outside the 24-hour Session Window**

If more than 24 hours have passed since the user last messaged you, any new outbound message you send must use a *WhatsApp message template*.

2. **One-time PIN (OTP), Marketing broadcasts, or Transactional Updates**

Templates are perfect for crucial communications such as OTPs, receipts, or other messages that must be sent when no active session exists.

***

#### Getting a Template Approved

{% stepper %}
{% step %}
**Create the Template**

Define the content of your message, including any placeholders (e.g., `{{1}}`, `{{2}}`) for personalization.
{% endstep %}

{% step %}
**Submit for Approval**

Once you submit a template, WhatsApp usually approves or rejects it within a few minutes using an **automated review**. If the system can’t handle it automatically, the template is sent for manual review, which may take up to 48 hours..
{% endstep %}

{% step %}
**Use the Approved Template**

After approval, you can send the template to any user. If the user replies, a new 24-hour session begins, allowing you to switch to free-form messages again.
{% endstep %}
{% endstepper %}

***

#### Key Points to Remember

* **24-Hour Session Window**: A session starts when a user sends a message to your business and remains active for 24 hours.
* **Unlimited Messages During a Session**: You can send and receive any number of messages while the session is open.
* **Renewing the Session**: If the user replies to your template or any message, it reopens or extends the session window by another 24 hours.
* **Template Content**: Templates must comply with WhatsApp’s policies. Ensure that your templates are clear and concise, and follow WhatsApp’s acceptable use guidelines to avoid rejection.

Read more [here](/reference/template-review-and-approval)


# Creating a Template

<mark style="color:green;">`POST`</mark> [`https://gateway.lipachat.com/api/v1/template/PHONE_NUMBER`](https://gateway.lipachat.com/api/v1/template/PHONE_NUMBER)

{% hint style="info" %}
Pass your WABA number or Sandbox phone number as the value of *PHONE\_NUMBER*
{% endhint %}

**Headers**

| Name         | Value                                                                          |
| ------------ | ------------------------------------------------------------------------------ |
| Content-Type | `application/json`                                                             |
| apiKey       | Get apiKey from App portal settings tab<https://app.lipachat.com/app/settings> |

**Body**

<table><thead><tr><th width="338">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>Name of template. Can only contain <strong>lowercase alphanumeric</strong> characters and underscores ( _ ). No other characters or white space are allowed.</td></tr><tr><td>language</td><td>string</td><td>Language code e.g en</td></tr><tr><td>category</td><td>string</td><td>Accepted values are: MARKETING, UTILITY or AUTHENTICATION.</td></tr><tr><td>component.header.format</td><td>string </td><td>Accepted values are: TEXT, IMAGE, VIDEO, DOCUMENT</td></tr><tr><td>component.header.text</td><td>string </td><td>Text to be sent on header</td></tr><tr><td>component.header.example</td><td>string </td><td>Should be present if text above has a variable.</td></tr><tr><td>component.body.text</td><td>string</td><td>Body text, accepts variables e.g Hello {{1}}, your balance is {{2}}</td></tr><tr><td>component.body.examples</td><td>array</td><td>Should match number of variables passed in text. For the example above it should be ['John', '2000']</td></tr><tr><td>component.footer.text</td><td>string</td><td>Optional footer text.</td></tr><tr><td>component.buttons[0].type</td><td>string</td><td>Accepted values are: PHONE_NUMBER, URL or QUICK_REPLY.</td></tr><tr><td>component.buttons[0].text</td><td>string</td><td>Text on button above.</td></tr><tr><td>component.buttons[0].phoneNumber</td><td>string</td><td>Should be passed if button type passed is PHONE_NUMBER.</td></tr><tr><td>component.buttons[0].url</td><td>string</td><td>Should be passed if button type passed is URL.</td></tr><tr><td>component.buttons[0].example</td><td>string</td><td>Applies for PHONE_NUMBER and URL.</td></tr></tbody></table>

> component.header, component.footer, component.buttons objects are optional.

Sample Requests:

<details>

<summary>Request to create a template with header and body.</summary>

```json
{
    "name": "temp_lower_68",
    "language": "en",
    "category": "MARKETING",
    "component": {
        "header": {
            "format": "TEXT",
            "text": "{{1}} registration",
            "example": "July"
        },
        "body": {
            "text": "Hi {{1}}, we have a new user registered click {{2}} to view.",
            "examples": [
                "John",
                "http://lipachat.com/offers/ASHSH"
            ]
        }
    }
}
```

</details>

<details>

<summary>Request to create a template with header, body and footer.</summary>

```json
{
    "name": "temp_lower_68",
    "language": "en",
    "category": "MARKETING",
    "component": {
        "header": {
            "format": "TEXT",
            "text": "{{1}} registration",
            "example": "July"
        },
        "body": {
            "text": "Hi {{1}}, we have a new user registered click {{2}} to view.",
            "examples": [
                "John",
                "http://lipachat.com/offers/ASHSH"
            ]
        },
        "footer": {
            "text": "Thank you"
        }
    }
}
```

</details>

<details>

<summary>Request to create a template with header, body and quick reply</summary>

```json
{
    "name": "transaction_update",
    "language": "en",
    "category": "UTILITY",
    "component": {
        "body": {
            "text": "Dear {{1}},\nYour {{2}} payment of {{3}} ",
            "examples": [
                "Mary",
                "Airtime",
                "KES 100"
            ]
        },
        "footer": {
            "text": "The Test Bank Team"
        },
        "buttons": [
            {
                "type": "QUICK_REPLY",
                "text": "Ask a Question"
            },
            {
                "type": "QUICK_REPLY",
                "text": "Chat with Support"
            }
        ]
    }
}
```

</details>

<details>

<summary>Request to create a template with quick reply buttons</summary>

```json
{
    "name": "lipachat_marketing_quick_reply",
    "language": "en",
    "category": "MARKETING",
    "component": {
        "body": {
            "text": "Hi {{1}}, we noticed that you tried to reach us but we were not available. Would you like to:",
            "examples": [
                "Mary"
            ]
        },
        "footer": null,
        "buttons": [
            {
                "type": "PHONE_NUMBER",
                "text": "CALL US",
                "phoneNumber": "+254110090747",
                "example": "254110090747"
            },
            {
                "type": "URL",
                "text": "Raise a ticket",
                "url": "https://lipachat.com/raiseTicket",
                "example": "https://lipachat.com/raiseTicket"
            }
        ]
    }
}
```

</details>

<details>

<summary>Request to create a template with a media header</summary>

```json

{
    "name": "payment_processed",
    "language": "en",
    "category": "UTILITY",
    "component": {
        "header": {
            "format": "IMAGE",
            "mediaId": "4:MS5qcGc=:aW1hZ2UvanBlZw==:ARbxC3pH-hnOZSObdto4tGAjuB2-INNLk98lRBxGZYLj5XtfKtQjGSzxp0V8fQde-7nmyvbzlpWY2bIvVYvNg8S8SpQyyUueV9xfvbKcPPd7sQ:e:1723555121:564683789153111:100074672771173:ARZ8O5E1vaOJ6415124"
        },
        "body": {
            "text": "Dear {{1}},\nYour {{2}} payment of {{3}} has been processed",
            "examples": [
                "Mary",
                "Funds Transfer",
                "KES 100"
            ]
        },
        "footer": {
            "text": "The Test Bank Team"
        },
        "buttons": [
            {
                "type": "QUICK_REPLY",
                "text": "Ask a Question"
            },
            {
                "type": "QUICK_REPLY",
                "text": "Chat with Support"
            }
        ]
    }
}
```

</details>

<details>

<summary>Request to create an authentication template</summary>

```json
{
    "name": "lipachat_auth_template",
    "language": "en",
    "category": "AUTHENTICATION",
    "component": {
        "body": {
            "addSecurityRecommendation": true // optional
        },
        "footer": {
            "codeExpirationMinutes": 10 // optional
        },
        "buttons": [
            {
                "type": "OTP",
                "otpType": "COPY_CODE",
                "text": "Copy Code"
            }
        ]
    }
}
```

</details>

**Response**

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

```json

{
    "timestamp": null,
    "data": {
        "id": "1661737361284034",
        "status": "APPROVED",
        "category": "MARKETING"
    },
    "status": "success",
    "message": "success",
    "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "timestamp": "2024-09-15T20:06:38.675567555",
    "data": null,
    "status": "error",
    "message": "Content in this language already exists",
    "errors": null
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "timestamp": "2024-09-15T20:07:23.464199513",
    "data": null,
    "status": "success",
    "message": "Invalid credentials",
    "errors": null
}
```

{% endtab %}
{% endtabs %}

### Uploading Template media

When creating a template with media on the header, you should first call the endpoint below to upload media then use the id returned to create the message template.

<mark style="color:green;">`POST`</mark> `https://gateway.lipachat.com/api/v1/template/upload/file`

**Headers**

| Name         | Value                                                                          |
| ------------ | ------------------------------------------------------------------------------ |
| Content-Type | multipart/form-data                                                            |
| apiKey       | Get apiKey from App portal settings tab<https://app.lipachat.com/app/settings> |

**Body**

| Name | Type | Description               |
| ---- | ---- | ------------------------- |
| file | file | Image, video or document. |

**Response**

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

```json
{
    "timestamp": null,
    "data": "4:V2hhdHNBcHAgSW1hZ2UgMjAyNC0wOS0xNSBhdCAxOS4wMS41MC5qcGVn:aW1hZ2UvanBlZw==:ARZi4gxBasbSbhXEXcfZSR7WtrgQCS-xs31BESau0ROb_fh2SFu1xndRAoY41h57QxRDZVsTFF3LyKGKIzxaRMwO_Q0xGZaw9XZ4LNEGqQrWEw:e:1726767043:564683789153111:100074672771173:ARbLETnUSOWfTwBzPfQ",
    "status": "success",
    "message": "success",
    "errors": null
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
use the value of *data* while calling create template endpoint, for templates with media in the header.
{% endhint %}

{% hint style="info" %}
Try out from Postman here [![Run In Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/1880882-362c9de0-8bff-4dbb-9596-194223a41ad8?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D1880882-362c9de0-8bff-4dbb-9596-194223a41ad8%26entityType%3Dcollection%26workspaceId%3D22009359-4643-460b-b79e-d2fed7c4e868#?env%5BLipachatWhatsappAPI%5D=W3sia2V5IjoiV0FfUEhPTkVfTlVNQkVSIiwidmFsdWUiOiIyNTQxMTAwOTA3NDciLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6IjI1NDExMDA5MDc0NyIsImNvbXBsZXRlU2Vzc2lvblZhbHVlIjoiMjU0MTEwMDkwNzQ3Iiwic2Vzc2lvbkluZGV4IjowfSx7ImtleSI6ImFwaUtleSIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQiLCJzZXNzaW9uVmFsdWUiOiIiLCJjb21wbGV0ZVNlc3Npb25WYWx1ZSI6IiIsInNlc3Npb25JbmRleCI6MX0seyJrZXkiOiJZT1VSX1BIT05FX05VTUJFUiIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQiLCJzZXNzaW9uVmFsdWUiOiIiLCJjb21wbGV0ZVNlc3Npb25WYWx1ZSI6IiIsInNlc3Npb25JbmRleCI6Mn1d)
{% endhint %}


# Updating a Template

```
PUT https://gateway.lipachat.com/api/v1/template/PHONE_NUMBER/:templateId
```

{% hint style="info" %}
Pass your WABA number or Sandbox phone number as the value of *PHONE\_NUMBER*
{% endhint %}

**Headers**

| Name         | Value                                                                           |
| ------------ | ------------------------------------------------------------------------------- |
| Content-Type | `application/json`                                                              |
| apiKey       | Get apiKey from App portal settings tab <https://app.lipachat.com/app/settings> |

**Body**

<table><thead><tr><th width="338">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>Name of template</td></tr><tr><td>language</td><td>string</td><td>Language code e.g en</td></tr><tr><td>category</td><td>string</td><td>Accepted values are: MARKETING, UTILITY or AUTHENTICATION.</td></tr><tr><td>component.header.format</td><td>string </td><td>Accepted values are: TEXT, IMAGE, VIDEO, DOCUMENT</td></tr><tr><td>component.header.text</td><td>string </td><td>Text to be sent on header</td></tr><tr><td>component.header.example</td><td>string </td><td>Should be present if text above has a variable.</td></tr><tr><td>component.body.text</td><td>string</td><td>Body text, accepts variables e.g Hello {{1}}, your balance is {{2}}</td></tr><tr><td>component.body.examples</td><td>array</td><td>Should match number of variables passed in text. For the example above it should be ['John', '2000']</td></tr><tr><td>component.footer.text</td><td>string</td><td>Optional footer text.</td></tr><tr><td>component.buttons[0].type</td><td>string</td><td>Accepted values are: PHONE_NUMBER, URL or QUICK_REPLY.</td></tr><tr><td>component.buttons[0].text</td><td>string</td><td>Text on button above.</td></tr><tr><td>component.buttons[0].phoneNumber</td><td>string</td><td>Should be passed if button type passed is PHONE_NUMBER.</td></tr><tr><td>component.buttons[0].url</td><td>string</td><td>Should be passed if button type passed is URL.</td></tr><tr><td>component.buttons[0].example</td><td>string</td><td>Applies for PHONE_NUMBER and URL.</td></tr></tbody></table>

> component.header, component.footer, component.buttons objects are optional.

<details>

<summary>Request to update a template with header and body.</summary>

```json
{
    "name": "test_campaign_utility2",
    "category": "MARKETING",
    "component": {
        "header": {
            "format": "TEXT",
            "text": "{{1}} sale",
            "example": "July"
        },
        "body": {
            "text": "Hi {{1}}, we have an offer for you, click on the link {{2}} to view it.",
            "examples": [
                "John",
                "http://lipachat.com/offers/ASHSH"
            ]
        }
    }
}
```

</details>

**Response**

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

```json
{
    "timestamp": null,
    "data": {
        "success": true,
        "error": null
    },
    "status": "success",
    "message": "success",
    "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "timestamp": "2024-09-15T20:06:38.675567555",
    "data": null,
    "status": "error",
    "message": "Content in this language already exists",
    "errors": null
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "timestamp": "2024-09-15T20:07:23.464199513",
    "data": null,
    "status": "success",
    "message": "Invalid credentials",
    "errors": null
}
```

{% endtab %}
{% endtabs %}


# Listing Message Templates

```
GET https://gateway.lipachat.com/api/v1/template/PHONE_NUMBER
```

{% hint style="info" %}
Pass your WABA number or Sandbox phone number as the value of *PHONE\_NUMBER*
{% endhint %}

**Headers**

| Name         | Value                                                                           |
| ------------ | ------------------------------------------------------------------------------- |
| Content-Type | `application/json`                                                              |
| apiKey       | Get apiKey from App portal settings tab <https://app.lipachat.com/app/settings> |

**Response**

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

```json
{
    "timestamp": null,
    "data": {
        "data": [
            {
                "name": "test_media_companya",
                "components": [
                    {
                        "type": "HEADER",
                        "format": "IMAGE",
                        "example": {
                            "header_handle": [
                                "https://scontent.whatsapp.net/v/t61.29466-34/328759101_1510667262890922_1348889753235210704_n.jpg?ccb=1-7&_nc_sid=8b1bef&_nc_ohc=PEok0_YRgNAQ7kNvgFpH0sc&_nc_ht=scontent.whatsapp.net&edm=AH51TzQEAAAA&_nc_gid=ANQFWqWAPaoLccD_WIYbSWd&oh=01_Q5AaID9X2olNqgUd21TyQEsfvScM3e1XFUqulVwqqyH08s7x&oe=673591AC"
                            ]
                        }
                    },
                    {
                        "type": "BODY",
                        "text": "Hi {{1}}, you recently bought airtime with our platform. We would like to hear your feedback on the quality. May we proceed with thr survey?",
                        "example": {
                            "body_text": [
                                [
                                    "example1"
                                ]
                            ]
                        }
                    },
                    {
                        "type": "BUTTONS",
                        "buttons": [
                            {
                                "type": "QUICK_REPLY",
                                "text": "Yes"
                            },
                            {
                                "type": "QUICK_REPLY",
                                "text": "No"
                            },
                            {
                                "type": "QUICK_REPLY",
                                "text": "Stop"
                            }
                        ]
                    }
                ],
                "language": "en",
                "status": "APPROVED",
                "category": "MARKETING",
                "id": "1510667259557589",
                "createdAt": null,
                "rejected_reason": "NONE",
                "quality_score": {
                    "score": "UNKNOWN",
                    "date": "1727275621"
                }
            },
            {
                "name": "test_media_temp",
                "components": [
                    {
                        "type": "HEADER",
                        "format": "TEXT",
                        "text": "Hello",
                        "example": {
                            "header_text": [
                                "example1"
                            ]
                        }
                    },
                    {
                        "type": "BODY",
                        "text": "Hello {{1}}",
                        "example": {
                            "body_text": [
                                [
                                    "example1"
                                ]
                            ]
                        }
                    }
                ],
                "language": "en",
                "status": "REJECTED",
                "category": "MARKETING",
                "id": "2815665278588373",
                "createdAt": null,
                "rejected_reason": "INVALID_FORMAT",
                "quality_score": {
                    "score": "UNKNOWN",
                    "date": "1728979833"
                }
            },
            {
                "name": "temp_lower_68",
                "components": [
                    {
                        "type": "HEADER",
                        "format": "TEXT",
                        "text": "{{1}} registration",
                        "example": {
                            "header_text": [
                                "July"
                            ]
                        }
                    },
                    {
                        "type": "BODY",
                        "text": "Hi {{1}}, we have a new user registered click {{2}} to view.",
                        "example": {
                            "body_text": [
                                [
                                    "John",
                                    "http://lipachat.com/offers/ASHSH"
                                ]
                            ]
                        }
                    }
                ],
                "language": "en",
                "status": "APPROVED",
                "category": "MARKETING",
                "id": "1661737361284034",
                "createdAt": "2024-09-15T17:05:52.808+00:00",
                "rejected_reason": "NONE",
                "quality_score": {
                    "score": "UNKNOWN",
                    "date": "1728979833"
                }
            }
        ]
    },
    "status": "success",
    "message": "success",
    "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "timestamp": "2024-09-15T20:06:38.675567555",
    "data": null,
    "status": "error",
    "message": "Content in this language already exists",
    "errors": null
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "timestamp": "2024-09-15T20:07:23.464199513",
    "data": null,
    "status": "success",
    "message": "Invalid credentials",
    "errors": null
}
```

{% endtab %}
{% endtabs %}


# Sending Message Templates

```http
POST https://gateway.lipachat.com/api/v1/whatsapp/template
```

**Headers**

| Name         | Value                                                                          |
| ------------ | ------------------------------------------------------------------------------ |
| Content-Type | `application/json`                                                             |
| apiKey       | Get apiKey from App portal settings tab<https://app.lipachat.com/app/settings> |

**Body**

| Name                                        | Type   | Description                                                                                                        |
| ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| messageId                                   | string | A unique identifier for the message. This will be used to track the message status and for deduplication purposes. |
| to                                          | string | PhonReceiver phone number. It should start with a country code.                                                    |
| from                                        | string | Sandbox number +254110090747 or your own WABA phone number.                                                        |
| template.name                               | string | Name of template                                                                                                   |
| template.language                           | string | Language code e.g en                                                                                               |
| template.category                           | string | Accepted values are: MARKETING, UTILITY or AUTHENTICATION                                                          |
| template.components.header.format           | string | Accepted values are: TEXT, IMAGE, VIDEO, DOCUMENT                                                                  |
| template.components.header.text             | string | Text to be sent on header                                                                                          |
| template.components.header.filename         | string | This is optional, applies to type document.                                                                        |
| template.components.header.example          | string | Should be present if text above has a variable.                                                                    |
| template.components.body.text               | string | Body text, accepts variables e.g Hello {{1}}, your balance is {{2}}                                                |
| template.components.body.examples           | array  | Should match number of variables passed in text. For the example above it should be \['John', '2000']              |
| template.components.footer.text             | string | Optional footer text.                                                                                              |
| template.components.buttons\[0].type        | string | Accepted values are: PHONE\_NUMBER, URL or QUICK\_REPLY.                                                           |
| template.components.buttons\[0].text        | string | Text on button above.                                                                                              |
| template.components.buttons\[0].phoneNumber | string | Should be passed if button type passed is PHONE\_NUMBER.                                                           |
| template.components.buttons\[0].url         | string | Should be passed if button type passed is URL.                                                                     |
| template.components.buttons\[0].example     | string | Applies for PHONE\_NUMBER and URL.                                                                                 |

**Example Requests:**

<details>

<summary>Request to send a template with type TEXT header.</summary>

```json
{
    "messageId": "d13ce19b-678f-4a94-a910-441cfbb25b9b",
    "to": "PHONE_NUMBER",
    "from": "BUSINESS_PHONE_NUMBER",
    "template": {
        "name": "offer_830",
        "languageCode": "en",
        "components": {
            "header": {
                "type": "TEXT",
                "parameter": "Discounts"
            },
            "body": {
                "placeholders": [
                    "John","123123"
                ]
            }
        }
    }
}
```

</details>

<details>

<summary>Request to send a template with type TEXT, no header.</summary>

```json
{
    "messageId": "5c9bd5ef-ebae-4071-9c26-3ba1ef693264",
    "to": "PHONE_NUMBER",
    "from": "BUSINESS_PHONE_NUMBER",
    "template": {
        "name": "offer_830",
        "languageCode": "en",
        "components": {
            "body": {
                "placeholders": [
                    "Gideon","123123"
                ]
            }
        }
    }
}
```

</details>

<details>

<summary>Request to send a template with type MEDIA (IMAGE, VIDEO, AUDIO) header.</summary>

```json
{
    "messageId": "5c9bd5ef-ebae-4071-9c26-3ba1ef693264",
    "to": "PHONE_NUMBER",
    "from": "BUSINESS_PHONE_NUMBER",
    "template": {
        "name": "declined_transfer",
        "languageCode": "en",
        "components": {
            "header":{
                "type": "IMAGE",
                "mediaUrl": "https://picsum.photos/id/237/200/300"
            },
            "body": {
                "placeholders": [
                    "John",
                    "Airtime",
                    "KES 100",
                    "Insufficient funds",
                    "funding your account"
                ]
            }
        }
    }
}
```

</details>

<details>

<summary>Request to send a template with type MEDIA (DOCUMENT) header.</summary>

```json
{
    "messageId": "5c9bd5ef-ebae-4071-9c26-3ba1ef693264",
    "to": "PHONE_NUMBER",
    "from": "BUSINESS_PHONE_NUMBER",
    "template": {
        "name": "transaction_alert",
        "languageCode": "en",
        "components": {
            "header":{
                "type": "DOCUMENT",
                "mediaUrl": "https://morth.nic.in/sites/default/files/dd12-13_0.pdf",
                "filename": "Transaction receipt"
            },
            "body": {
                "placeholders": [
                    "John",
                    "Airtime",
                    "KES 100"
                ]
            }
        }
    }
}
```

</details>

<details>

<summary>Request to send an Authentication template</summary>

```json
{
    "messageId": "{{$randomUUID}}",
    "to": "{{YOUR_PHONE_NUMBER}}",
    "from": "{{BUSINESS_PHONE_NUMBER}}",
    "template": {
        "name": "lipachat_auth_template",
        "languageCode": "en",
        "components": {
            "body": {
                "placeholders": [
                    "123456"
                ]
            },
            "buttons": [
                {
                    "type": "URL",
                    "index": 0,
                    "parameter": "123456"
                }
            ]
        }
    }
}
```

</details>

<details>

<summary>Request to send a template with no params</summary>

```json
{
    "messageId": "{{$randomUUID}}",
    "to": "{{YOUR_PHONE_NUMBER}}",
    "from": "{{BUSINESS_PHONE_NUMBER}}",
    "template": {
        "name": "template_with_no_params",
        "languageCode": "en",
        "components": {
        }
    }
}
```

</details>

**Response**

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

```json
{
  "timestamp": "2023-11-22T09:59:26.720575619",
  "data": {
    "messageId": "4530f474-9d84-4905-a26f-6ba473ab890d",
    "waId": "wamid.HBgMMjU0NzE3NzQ2NTY1FQIAERgSMjNCREE1Q0YwQUJFQzE0NUQ2AA==",
    "status": "SENT",
    "statusDesc": "Template sent successfully"
  },
  "status": "success",
  "message": "",
  "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "timestamp": "2024-09-15T20:06:38.675567555",
    "data": null,
    "status": "error",
    "message": "Request failed. please provide missing content",
    "errors": null
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "timestamp": "2024-09-15T20:07:23.464199513",
    "data": null,
    "status": "success",
    "message": "Invalid credentials",
    "errors": null
}
```

{% endtab %}
{% endtabs %}


# Free-Form Messages

🔒 WhatsApp 24-Hour Session Rule

> Before sending a free-form message, make sure the WhatsApp session with the user is **active**.
>
> **If the user has not messaged your business within the last 24 hours, WhatsApp requires the first message to be a&#x20;*****template message***.
>
> After the customer replies, the 24-hour session opens and you may send free-form messages using this API.\
> **For sandbox testing**, send your join code to the sandbox number to activate your session.\
> [Learn more](https://app.gitbook.com/o/rJyj7TfON4zeW56KoQjM/s/2JHt6V4YwZLX6ZUdLqMy/~/changes/87/guides/joincodes)

<mark style="color:green;">`POST`</mark> <https://gateway.lipachat.com/api/v1/whatsapp/message/text>

Used to send free form messages to users.

**Headers**

| Name         | Value                                                                          |
| ------------ | ------------------------------------------------------------------------------ |
| Content-Type | `application/json`                                                             |
| apiKey       | Get apiKey from App portal settings tab<https://app.lipachat.com/app/settings> |

**Body**

| Name      | Type   | Description                                                                                                        |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| messageId | string | A unique identifier for the message. This will be used to track the message status and for deduplication purposes. |
| message   | string | The message being sent.                                                                                            |
| from      | string | Sandbox number +254110090747 or your own WABA phone number.                                                        |
| to        | string | Receiver phone number. It should start with a country code.                                                        |

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

```sh
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/message/text' \
--header 'apiKey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "message": "Hello world",
    "messageId": "e66fc7b8-680f-4887-8dc8-ee062d65b54f",
    "to": "254XXXXXXX",
    "from": "254110090747"
}'
```

{% endtab %}

{% tab title="Java" %}

```java
// Create an instance of OkHttpClient
OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

// Define the media type for the request
MediaType mediaType = MediaType.parse("application/json");

// Create the request body with the necessary JSON payload using a text block
RequestBody body = RequestBody.create(mediaType, """
{
    "message": "Hello world",
    "messageId": "91a0cda6-9454-4150-b536-21cf6491e37b",
    "to": "PHONE_NUMBER",
    "from": "+254110090747"
}
""");

// Build the request with the required headers
Request request = new Request.Builder()
    .url("https://gateway.lipachat.com/api/v1/whatsapp/message/text")
    .method("POST", body)
    .addHeader("apiKey", "YOUR_API_KEY")
    .addHeader("Content-Type", "application/json")
    .build();

// Execute the request and get the response
Response response = client.newCall(request).execute();

```

{% endtab %}

{% tab title="Javascript" %}

```ruby
const axios = require('axios');
let data = JSON.stringify({
  "message": "Hello world",
  "messageId": "307d4b95-6892-403c-a777-8297a0c375de",
  "to": "254XXXXXXX",
  "from": "+254110090747"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://gateway.lipachat.com/api/v1/whatsapp/message/text',
  headers: { 
    'apiKey': 'YOUR_API_KEY', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

```

{% endtab %}
{% endtabs %}

**Response**

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

```json
{
      "timestamp": "2023-08-06T01:27:56.825898971",
      "data": {
            "messageId": "7addc006-07db-4fae-aac5-b285903b41d4",
            "waId": "wamid.HBgMMjU0NzE3NzQ2NTY1FQIAEnRgSRjJGRkMzNkQ0QUVENTIxQ0NBAA==",
            "status": "SENT",
            "statusDesc": "Message sent successfully"
      },
      "status": "success",
      "message": "",
      "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
      "timestamp": "2023-08-06T17:50:35.701+00:00",
      "status": 400,
      "error": "Bad Request",
      "path": "/api/v1/whatsapp/message/text"
}
```

{% endtab %}

{% tab title="401" %}

```json
{
      "timestamp": "2023-08-06T20:49:48.455464058",
      "data": null,
      "status": "success",
      "message": "Invalid credentials",
      "errors": null
}
```

{% endtab %}
{% endtabs %}


# Sending Media

🔒 WhatsApp 24-Hour Session Rule

> Before sending media, make sure the WhatsApp session with the user is **active**.
>
> **If the user has not messaged your business within the last 24 hours, WhatsApp requires the first message to be a&#x20;*****template message***.
>
> After the customer replies, the 24-hour session opens and you may send media messages using this API.\
> **For sandbox testing**, send your join code to the sandbox number to activate your session.\
> [Learn more](https://app.gitbook.com/o/rJyj7TfON4zeW56KoQjM/s/2JHt6V4YwZLX6ZUdLqMy/~/changes/87/guides/joincodes)

<mark style="color:green;">`POST`</mark> <https://gateway.lipachat.com/api/v1/whatsapp/media>

This API enables users to send Images, Videos, or Audio.

**Headers**

| Name         | Value                                                                           |
| ------------ | ------------------------------------------------------------------------------- |
| Content-Type | `application/json`                                                              |
| apiKey       | Get apiKey from App portal settings tab <https://app.lipachat.com/app/settings> |

**Body**

| Name      | Type   | Description                                                                                                        |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| messageId | string | A unique identifier for the message. This will be used to track the message status and for deduplication purposes. |
| mediaType | string | Pass value as IMAGE, VIDEO, AUDIO, DOCUMENT or STICKER                                                             |
| mediaUrl  | string | URL of an image to be sent. Must be a valid URL starting with https\://...                                         |
| caption   | string | Media caption. Optional.                                                                                           |
| filename  | string | Optional, applies to Document.                                                                                     |
| from      | string | Sandbox number +254110090747 or your own WABA phone number.                                                        |
| to        | string | Receiver phone number. It should start with a country code.                                                        |

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

```sh
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/media' \
--header 'apiKey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "messageId": "5d3f62c3-eb8f-4150-8941-bdceb0f429bb",
    "to": "254XXXXX",
    "from": "254110090747",
    "mediaType": "IMAGE",
    "mediaUrl": "https://picsum.photos/id/237/200/300",
    "caption": ""
}'
```

{% endtab %}

{% tab title="Java" %}

```java
// Create an instance of OkHttpClient
OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

// Define the media type for the request
MediaType mediaType = MediaType.parse("application/json");

// Create the request body with the necessary JSON payload using a text block
RequestBody body = RequestBody.create(mediaType, """
{
    "messageId": "5d3f62c3-eb8f-4150-8941-bdceb0f429bb",
    "to": "254XXXXX",
    "from": "254110090747",
    "mediaType": "IMAGE",
    "mediaUrl": "https://picsum.photos/id/237/200/300",
    "caption": ""
}
""");

// Build the request with the required headers
Request request = new Request.Builder()
    .url("https://gateway.lipachat.com/api/v1/whatsapp/media")
    .method("POST", body)
    .addHeader("apiKey", "YOUR_API_KEY")
    .addHeader("Content-Type", "application/json")
    .build();

// Execute the request and get the response
Response response = client.newCall(request).execute();

```

{% endtab %}

{% tab title="Javascript" %}

```ruby
const axios = require('axios');
let data = JSON.stringify({
    "messageId": "5d3f62c3-eb8f-4150-8941-bdceb0f429bb",
    "to": "254XXXXX",
    "from": "254110090747",
    "mediaType": "IMAGE",
    "mediaUrl": "https://picsum.photos/id/237/200/300",
    "caption": ""
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://gateway.lipachat.com/api/v1/whatsapp/media',
  headers: { 
    'apiKey': 'YOUR_API_KEY', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

```

{% endtab %}
{% endtabs %}

<details>

<summary>Sample Requests</summary>

Send Image

```json
{
	"messageId": "{{$randomUUID}}",
	"to": "{{YOUR_PHONE_NUMBER}}",
	"from": "{{WA_PHONE_NUMBER}}",
	"mediaType": "IMAGE",
	"mediaUrl": "https://picsum.photos/id/237/200/300",
	"caption": "Test caption"
}
```

Send Video

```json
{
	"messageId": "{{$randomUUID}}",
	"to": "{{YOUR_PHONE_NUMBER}}",
	"from": "{{WA_PHONE_NUMBER}}",
	"mediaType": "VIDEO",
	"mediaUrl": "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerFun.mp4",
	"caption": "Test caption"
}
```

Send Audio

```json
{
	"messageId": "{{$randomUUID}}",
	"to": "{{YOUR_PHONE_NUMBER}}",
	"from": "{{WA_PHONE_NUMBER}}",
	"mediaType": "AUDIO",
	"mediaUrl": "https://www2.cs.uic.edu/~i101/SoundFiles/BabyElephantWalk60.wav",
	"caption": "Optional Caption"
}
```

Send Document

```json
{
    "messageId": "{{$randomUUID}}",
    "to": "{{YOUR_PHONE_NUMBER}}",
    "from": "{{YOUR_PHONE_NUMBER}}",
    "mediaType": "DOCUMENT",
    "mediaUrl": "https://media_url.pdf",
    "filename": "insurance_policy.pdf",
    "caption": "Please find attached"
}
```

</details>

**Response**

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

```json
{
      "timestamp": "2023-08-06T01:27:56.825898971",
      "data": {
            "messageId": "7addc006-07db-4fae-aac5-b285903b41d4",
            "waId": "wamid.HBgMMjU0NzE3NzQ2NTY1FQIAEnRgSRjJGRkMzNkQ0QUVENTIxQ0NBAA==",
            "status": "SENT",
            "statusDesc": "Media sent successfully"
      },
      "status": "success",
      "message": "",
      "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
      "timestamp": "2023-08-06T17:50:35.701+00:00",
      "status": 400,
      "error": "Bad Request",
      "path": "/api/v1/whatsapp/message/text"
}
```

{% endtab %}

{% tab title="401" %}

```json
{
      "timestamp": "2023-08-06T20:49:48.455464058",
      "data": null,
      "status": "success",
      "message": "Invalid credentials",
      "errors": null
}
```

{% endtab %}
{% endtabs %}


# Sending Buttons

🔒 WhatsApp 24-Hour Session Rule

> Before sending buttons, make sure the WhatsApp session with the user is **active**.
>
> **If the user has not messaged your business within the last 24 hours, WhatsApp requires the first message to be a&#x20;*****template message***.
>
> After the customer replies, the 24-hour session opens and you may send button messages using this API.\
> **For sandbox testing**, send your join code to the sandbox number to activate your session.\
> [Learn more](https://app.gitbook.com/o/rJyj7TfON4zeW56KoQjM/s/2JHt6V4YwZLX6ZUdLqMy/~/changes/87/guides/joincodes)

WhatsApp offers an API to send quick reply buttons to users. You can send up to a maximum of three buttons. To send more, consider using [Sending Interactive Lists](/api/sending-interactive-lists)

<div align="center" data-full-width="true"><figure><img src="/files/tPFTmJs1hetBhwkQ90RY" alt="" width="375"><figcaption></figcaption></figure></div>

<mark style="color:green;">`POST`</mark> <https://gateway.lipachat.com/api/v1/whatsapp/interactive/buttons>

**Headers**

| Name         | Value                                                                          |
| ------------ | ------------------------------------------------------------------------------ |
| Content-Type | `application/json`                                                             |
| apiKey       | Get apiKey from App portal settings tab<https://app.lipachat.com/app/settings> |

**Body**

| Name              | Type   | Description                                                                                                        |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| messageId         | string | A unique identifier for the message. This will be used to track the message status and for deduplication purposes. |
| message           | string | The message being sent.                                                                                            |
| from              | string | Sandbox number +254110090747 or your own WABA phone number.                                                        |
| to                | string | Receiver phone number. It should start with a country code.                                                        |
| buttons\[0].id    | string | Unique identifier of button in your app. eg 1 or YES\_BTN                                                          |
| buttons\[0].title | string | Text to be shown on button                                                                                         |

{% hint style="info" %}
"*buttons*" field is a list or array that accepts a minimum of 1 items and  a maximum of 3 items.
{% endhint %}

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

```sh
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/interactive/buttons' \
--header 'apiKey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "text": "Hello John Doe, are you interested to learn more about our products?",
  "buttons": [
    {
      "id": "1",
      "title": "YES"
    },
    {
      "id": "2",
      "title": "NO"
    },
    {
      "id": "3",
      "title": "Maybe"
    }
  ],
  "messageId": "875d25c2-0cb1-4270-a536-7b6dc16568b5",
  "to": "254XXXXX",
  "from": "254110090747"
}'
```

{% endtab %}

{% tab title="Java" %}

```java
// Create an instance of OkHttpClient
OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

// Define the media type for the request
MediaType mediaType = MediaType.parse("application/json");

// Create the request body with the necessary JSON payload using a text block
RequestBody body = RequestBody.create(mediaType, """
{
  "text": "Hello John Doe, are you interested to learn more about our products?",
  "buttons": [
    {
      "id": "1",
      "title": "YES"
    },
    {
      "id": "2",
      "title": "NO"
    },
    {
      "id": "3",
      "title": "Maybe"
    }
  ],
  "messageId": "9f1a77f0-2240-4027-af00-c8d90469068b",
  "to": "254XXXXX",
  "from": "254110090747"
}
""");

// Build the request with the required headers
Request request = new Request.Builder()
    .url("https://gateway.lipachat.com/api/v1/whatsapp/interactive/buttons")
    .method("POST", body)
    .addHeader("apiKey", "YOUR_API_KEY")
    .addHeader("Content-Type", "application/json")
    .build();

// Execute the request and get the response
Response response = client.newCall(request).execute();


```

{% endtab %}

{% tab title="Javascript" %}

```ruby
const axios = require('axios');
let data = JSON.stringify({
  "text": "Hello John Doe, are you interested to learn more about our products?",
  "buttons": [
    {
      "id": "1",
      "title": "YES"
    },
    {
      "id": "2",
      "title": "NO"
    },
    {
      "id": "3",
      "title": "Maybe"
    }
  ],
  "messageId": "a1950882-b248-4f40-be1c-231bf64b024d",
  "to": "254XXXXX",
  "from": "254110090747"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://gateway.lipachat.com/api/v1/whatsapp/interactive/buttons',
  headers: { 
    'apiKey': 'YOUR_API_KEY', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});


```

{% endtab %}
{% endtabs %}

**Response**

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

```json
{
      "timestamp": "2023-08-06T01:27:56.825898971",
      "data": {
            "messageId": "7addc006-07db-4fae-aac5-b285903b41d4",
            "waId": "wamid.HBgMMjU0NzE3NzQ2NTY1FQIAEnRgSRjJGRkMzNkQ0QUVENTIxQ0NBAA==",
            "status": "SENT",
            "statusDesc": "Message sent successfully"
      },
      "status": "success",
      "message": "",
      "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
      "timestamp": "2023-08-06T17:50:35.701+00:00",
      "status": 400,
      "error": "Bad Request",
      "path": "/api/v1/whatsapp/message/text"
}
```

{% endtab %}

{% tab title="401" %}

```json
{
      "timestamp": "2023-08-06T20:49:48.455464058",
      "data": null,
      "status": "success",
      "message": "Invalid credentials",
      "errors": null
}
```

{% endtab %}
{% endtabs %}


# Sending Interactive Lists

🔒 WhatsApp 24-Hour Session Rule

> Before sending interactive lists, make sure the WhatsApp session with the user is **active**.
>
> **If the user has not messaged your business within the last 24 hours, WhatsApp requires the first message to be a&#x20;*****template message***.
>
> After the customer replies, the 24-hour session opens and you may send interactive lists using this API.\
> **For sandbox testing**, send your join code to the sandbox number to activate your session.\
> [Learn more](https://app.gitbook.com/o/rJyj7TfON4zeW56KoQjM/s/2JHt6V4YwZLX6ZUdLqMy/~/changes/87/guides/joincodes)

WhatsApp offers an API to send lists.

![](/files/ojDsOCwVHLCS41IwVgXM)![](/files/d4Ffnb0SHRN9b0MCAZUh)&#x20;

<mark style="color:green;">`POST`</mark> [https://gateway.lipachat.com/api/v1/whatsapp/interactive](https://gateway.lipachat.com/api/v1/whatsapp/interactive/buttons)<mark style="color:blue;">/list</mark>

**Headers**

| Name         | Value                                                                          |
| ------------ | ------------------------------------------------------------------------------ |
| Content-Type | `application/json`                                                             |
| apiKey       | Get apiKey from App portal settings tab<https://app.lipachat.com/app/settings> |

**Body**

<table><thead><tr><th width="348">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>messageId</td><td>string</td><td>A unique identifier for the message. This will be used to track the message status and for deduplication purposes.</td></tr><tr><td>message</td><td>string</td><td>The message being sent.</td></tr><tr><td>from</td><td>string</td><td>Sandbox number +254110090747 or your own WABA phone number.</td></tr><tr><td>to</td><td>string</td><td>Receiver phone number. It should start with a country code.</td></tr><tr><td>buttons[0].sectionTitle</td><td>string</td><td></td></tr><tr><td>buttons[0].sectionItems[0].id</td><td>string</td><td>Unique identifier of button in your app. eg 1 or YES_BTN</td></tr><tr><td>buttons[0].sectionItems[0].title</td><td>string</td><td>Text to be displayed to user.</td></tr><tr><td>buttons[0].sectionItems[0].description</td><td>string</td><td>Optional description</td></tr></tbody></table>

{% hint style="info" %}
For interactive list messages, WhatsApp allows up to 10 sections, with a maximum of 10 rows across all sections combined.
{% endhint %}

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

```sh
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/interactive/list' \
--header 'apiKey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "headerText": "Welcome to Lipachat",
  "body": "Please choose a product you would like below",
  "buttonText": "Click Here",
  "buttons": [
    {
      "sectionTitle": "Airtime",
      "sectionItems": [
        {
          "id": "SAFARICOM_AIRTIME",
          "title": "Safaricom",
          "description": "mpesa network"
        },
        {
          "id": "AIRTEL_AIRTIME",
          "title": "Airtel",
          "description": "airtel money"
        }
      ]
    },
    {
      "sectionTitle": "Bill Payment",
      "sectionItems": [
        {
          "id": "KPLC",
          "title": "KPLC",
          "description": "electricity"
        },
        {
          "id": "NAIROBI_WATER",
          "title": "Nairobi Water",
          "description": "county gov water"
        }
      ]
    }
  ],
  "messageId": "ca739107-4b0d-4581-acb1-4c4af70555de",
  "to": "2547XXXX",
  "from": "254110090747"
}'
```

{% endtab %}

{% tab title="Java" %}

```java
// Create an instance of OkHttpClient
OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

// Define the media type for the request
MediaType mediaType = MediaType.parse("application/json");

// Create the request body with the necessary JSON payload using a text block
RequestBody body = RequestBody.create(mediaType, """
{
  "headerText": "Welcome to Lipachat",
  "body": "Please choose a product you would like below",
  "buttonText": "Click Here",
  "buttons": [
    {
      "sectionTitle": "Airtime",
      "sectionItems": [
        {
          "id": "SAFARICOM_AIRTIME",
          "title": "Safaricom",
          "description": "mpesa network"
        },
        {
          "id": "AIRTEL_AIRTIME",
          "title": "Airtel",
          "description": "airtel money"
        }
      ]
    },
    {
      "sectionTitle": "Bill Payment",
      "sectionItems": [
        {
          "id": "KPLC",
          "title": "KPLC",
          "description": "electricity"
        },
        {
          "id": "NAIROBI_WATER",
          "title": "Nairobi Water",
          "description": "county gov water"
        }
      ]
    }
  ],
  "messageId": "ca739107-4b0d-4581-acb1-4c4af70555de",
  "to": "254XXXXX",
  "from": "254110090747"
}
""");

// Build the request with the required headers
Request request = new Request.Builder()
    .url("https://gateway.lipachat.com/api/v1/whatsapp/interactive/list")
    .method("POST", body)
    .addHeader("apiKey", "YOUR_API_KEY")
    .addHeader("Content-Type", "application/json")
    .build();

// Execute the request and get the response
Response response = client.newCall(request).execute();



```

{% endtab %}

{% tab title="Javascript" %}

```ruby
const axios = require('axios');
let data = JSON.stringify({
  "headerText": "Welcome to Lipachat",
  "body": "Please choose a product you would like below",
  "buttonText": "Click Here",
  "buttons": [
    {
      "sectionTitle": "Airtime",
      "sectionItems": [
        {
          "id": "SAFARICOM_AIRTIME",
          "title": "Safaricom",
          "description": "mpesa network"
        },
        {
          "id": "AIRTEL_AIRTIME",
          "title": "Airtel",
          "description": "airtel money"
        }
      ]
    },
    {
      "sectionTitle": "Bill Payment",
      "sectionItems": [
        {
          "id": "KPLC",
          "title": "KPLC",
          "description": "electricity"
        },
        {
          "id": "NAIROBI_WATER",
          "title": "Nairobi Water",
          "description": "county gov water"
        }
      ]
    }
  ],
  "messageId": "ca739107-4b0d-4581-acb1-4c4af70555de",
  "to": "254XXXXX",
  "from": "254110090747"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://gateway.lipachat.com/api/v1/whatsapp/interactive/list',
  headers: { 
    'apiKey': 'YOUR_API_KEY', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

```

{% endtab %}
{% endtabs %}

**Response**

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

```json
{
      "timestamp": "2023-08-06T01:27:56.825898971",
      "data": {
            "messageId": "7addc006-07db-4fae-aac5-b285903b41d4",
            "waId": "wamid.HBgMMjU0NzE3NzQ2NTY1FQIAEnRgSRjJGRkMzNkQ0QUVENTIxQ0NBAA==",
            "status": "SENT",
            "statusDesc": "Message sent successfully"
      },
      "status": "success",
      "message": "",
      "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
      "timestamp": "2023-08-06T17:50:35.701+00:00",
      "status": 400,
      "error": "Bad Request",
      "path": "/api/v1/whatsapp/message/text"
}
```

{% endtab %}

{% tab title="401" %}

```json
{
      "timestamp": "2023-08-06T20:49:48.455464058",
      "data": null,
      "status": "success",
      "message": "Invalid credentials",
      "errors": null
}
```

{% endtab %}
{% endtabs %}


# Sending Contacts

🔒 WhatsApp 24-Hour Session Rule

> Before sending a contact, make sure the WhatsApp session with the user is **active**.
>
> **If the user has not messaged your business within the last 24 hours, WhatsApp requires the first message to be a&#x20;*****template message***.
>
> After the customer replies, the 24-hour session opens and you may send contacts using this API.\
> **For sandbox testing**, send your join code to the sandbox number to activate your session.\
> [Learn more](https://app.gitbook.com/o/rJyj7TfON4zeW56KoQjM/s/2JHt6V4YwZLX6ZUdLqMy/~/changes/87/guides/joincodes)

WhatsApp offers an API to send contacts.

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

<mark style="color:green;">`POST`</mark>&#x20;

```url
https://gateway.lipachat.com/api/v1/whatsapp/contact
```

**Headers**

| Name         | Value                                                                          |
| ------------ | ------------------------------------------------------------------------------ |
| Content-Type | `application/json`                                                             |
| apiKey       | Get apiKey from App portal settings tab<https://app.lipachat.com/app/settings> |

**Body**

<table><thead><tr><th width="348">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>messageId</td><td>string</td><td>A unique identifier for the message. This will be used to track the message status and for deduplication purposes.</td></tr><tr><td>from</td><td>string</td><td>Sandbox number +254110090747 or your own WABA phone number.</td></tr><tr><td>to</td><td>string</td><td>Receiver phone number. It should start with a country code.</td></tr><tr><td>name.formattedName</td><td>String</td><td>Contact's formatted name. This will appear in the message alongside the profile arrow button.</td></tr><tr><td>phones[0].phone[0].phone</td><td>string</td><td>User phone number.</td></tr><tr><td>phones[0].phone[0].type</td><td>string</td><td>Type of phone number. For example, cell, mobile, main, iPhone, home, work, etc.</td></tr><tr><td>phones[0].phone[0].waId</td><td>string</td><td>WhatsApp user ID. If omitted, the message will display an Invite to WhatsApp button instead of the standard buttons.</td></tr></tbody></table>

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

```sh
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/contact' \
--header 'apiKey: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "messageId": "ca739107-4b0d-4581-acb1-4c4af70555de",
    "to": "2547XXXX",
    "from": "254110090747",
    "name": {
        "formattedName": "Test User"
    },
    "phones": [
        {
            "phone": "254712345678",
            "type": "Cell",
            "waId": "254712345678"
        }
    ]
}'
```

{% endtab %}

{% tab title="Java" %}

```java
// Create an instance of OkHttpClient
OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

// Define the media type for the request
MediaType mediaType = MediaType.parse("application/json");

// Create the request body with the necessary JSON payload using a text block
RequestBody body = RequestBody.create(mediaType, """
{
    "messageId": "ca739107-4b0d-4581-acb1-4c4af70555de",
    "to": "2547XXXX",
    "from": "254110090747",
    "name": {
        "formattedName": "Test User"
    },
    "phones": [
        {
            "phone": "254712345678",
            "type": "Cell",
            "waId": "254712345678"
        }
    ]
}
""");

// Build the request with the required headers
Request request = new Request.Builder()
    .url("https://gateway.lipachat.com/api/v1/whatsapp/contact")
    .method("POST", body)
    .addHeader("apiKey", "YOUR_API_KEY")
    .addHeader("Content-Type", "application/json")
    .build();

// Execute the request and get the response
Response response = client.newCall(request).execute();






```

{% endtab %}

{% tab title="Javascript" %}

```ruby
const axios = require('axios');
let data = JSON.stringify({
    "messageId": "ca739107-4b0d-4581-acb1-4c4af70555de",
    "to": "2547XXXX",
    "from": "254110090747",
    "name": {
        "formattedName": "Test User"
    },
    "phones": [
        {
            "phone": "254712345678",
            "type": "Cell",
            "waId": "254712345678"
        }
    ]
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://gateway.lipachat.com/api/v1/whatsapp/contact',
  headers: { 
    'apiKey': 'YOUR_API_KEY', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});


```

{% endtab %}
{% endtabs %}

**Response**

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

```json
{
      "timestamp": "2023-08-06T01:27:56.825898971",
      "data": {
            "messageId": "7addc006-07db-4fae-aac5-b285903b41d4",
            "waId": "wamid.HBgMMjU0NzE3NzQ2NTY1FQIAEnRgSRjJGRkMzNkQ0QUVENTIxQ0NBAA==",
            "status": "SENT",
            "statusDesc": "Message sent successfully"
      },
      "status": "success",
      "message": "",
      "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
      "timestamp": "2023-08-06T17:50:35.701+00:00",
      "status": 400,
      "error": "Bad Request",
      "path": "/api/v1/whatsapp/contact"
}
```

{% endtab %}

{% tab title="401" %}

```json
{
      "timestamp": "2023-08-06T20:49:48.455464058",
      "data": null,
      "status": "success",
      "message": "Invalid credentials",
      "errors": null
}
```

{% endtab %}
{% endtabs %}


# Location

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td>Send Location</td><td><a href="/files/sViP38jjktW3KZiAABrR">/files/sViP38jjktW3KZiAABrR</a></td></tr><tr><td>Request Location</td><td><a href="/files/CV3HxdmcYY1gS1hu0m2U">/files/CV3HxdmcYY1gS1hu0m2U</a></td></tr></tbody></table>


# Sending Location

🔒 WhatsApp 24-Hour Session Rule

> Before sending a location, make sure the WhatsApp session with the user is **active**.
>
> **If the user has not messaged your business within the last 24 hours, WhatsApp requires the first message to be a&#x20;*****template message***.
>
> After the customer replies, the 24-hour session opens and you may send location messages using this API.\
> **For sandbox testing**, send your join code to the sandbox number to activate your session.\
> [Learn more](https://app.gitbook.com/o/rJyj7TfON4zeW56KoQjM/s/2JHt6V4YwZLX6ZUdLqMy/~/changes/87/guides/joincodes)

WhatsApp offers an API to send location.

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

<mark style="color:green;">`POST`</mark>&#x20;

```url
https://gateway.lipachat.com/api/v1/whatsapp/location
```

**Headers**

| Name         | Value                                                                          |
| ------------ | ------------------------------------------------------------------------------ |
| Content-Type | `application/json`                                                             |
| apiKey       | Get apiKey from App portal settings tab<https://app.lipachat.com/app/settings> |

**Body**

<table><thead><tr><th width="348">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>messageId</td><td>string</td><td>A unique identifier for the message. This will be used to track the message status and for deduplication purposes.</td></tr><tr><td>from</td><td>string</td><td>Sandbox number +254110090747 or your own WABA phone number.</td></tr><tr><td>to</td><td>string</td><td>Receiver phone number. It should start with a country code.</td></tr><tr><td>latitude</td><td>number</td><td>Location latitude in decimal degrees. e.g 35.929673</td></tr><tr><td>longtitude</td><td>number</td><td>Location longtitude in degrees. e.g -78.948237</td></tr><tr><td>name</td><td>string</td><td>Location name</td></tr><tr><td>address</td><td>string</td><td>Location address</td></tr></tbody></table>

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

```sh
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/location' \
--header 'apiKey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "messageId": "ee835207-a20b-49ef-b270-e29ed7da351e",
    "to": "2547XXXX",
    "from": "254110090747",
    "latitude": "35.929673",
    "longitude": "-78.948237",
    "name": "Church",
    "address": "Christ the King, off broad way"
}'
```

{% endtab %}

{% tab title="Java" %}

```java
// Create an instance of OkHttpClient
OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

// Define the media type for the request
MediaType mediaType = MediaType.parse("application/json");

// Create the request body with the necessary JSON payload using a text block
RequestBody body = RequestBody.create(mediaType, """
{
    "messageId": "ee835207-a20b-49ef-b270-e29ed7da351e",
    "to": "2547XXXX",
    "from": "254110090747",
    "latitude": "35.929673",
    "longitude": "-78.948237",
    "name": "Church",
    "address": "Christ the King, off broad way"
}
""");

// Build the request with the required headers
Request request = new Request.Builder()
    .url("https://gateway.lipachat.com/api/v1/whatsapp/location")
    .method("POST", body)
    .addHeader("apiKey", "YOUR_API_KEY")
    .addHeader("Content-Type", "application/json")
    .build();

// Execute the request and get the response
Response response = client.newCall(request).execute();



```

{% endtab %}

{% tab title="Javascript" %}

```ruby
const axios = require('axios');
let data = JSON.stringify({
    "messageId": "ee835207-a20b-49ef-b270-e29ed7da351e",
    "to": "2547XXXX",
    "from": "254110090747",
    "latitude": "35.929673",
    "longitude": "-78.948237",
    "name": "Church",
    "address": "Christ the King, off broad way"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://gateway.lipachat.com/api/v1/whatsapp/location',
  headers: { 
    'apiKey': 'YOUR_API_KEY', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

```

{% endtab %}
{% endtabs %}

**Response**

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

```json
{
      "timestamp": "2023-08-06T01:27:56.825898971",
      "data": {
            "messageId": "7addc006-07db-4fae-aac5-b285903b41d4",
            "waId": "wamid.HBgMMjU0NzE3NzQ2NTY1FQIAEnRgSRjJGRkMzNkQ0QUVENTIxQ0NBAA==",
            "status": "SENT",
            "statusDesc": "Message sent successfully"
      },
      "status": "success",
      "message": "",
      "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
      "timestamp": "2023-08-06T17:50:35.701+00:00",
      "status": 400,
      "error": "Bad Request",
      "path": "/api/v1/whatsapp/location"
}
```

{% endtab %}

{% tab title="401" %}

```json
{
      "timestamp": "2023-08-06T20:49:48.455464058",
      "data": null,
      "status": "success",
      "message": "Invalid credentials",
      "errors": null
}
```

{% endtab %}
{% endtabs %}


# Request Location

🔒 WhatsApp 24-Hour Session Rule

> Before requesting for a location, make sure the WhatsApp session with the user is **active**.
>
> **If the user has not messaged your business within the last 24 hours, WhatsApp requires the first message to be a&#x20;*****template message***.
>
> After the customer replies, the 24-hour session opens and you may request  a location using this API.\
> **For sandbox testing**, send your join code to the sandbox number to activate your session.\
> [Learn more](https://app.gitbook.com/o/rJyj7TfON4zeW56KoQjM/s/2JHt6V4YwZLX6ZUdLqMy/~/changes/87/guides/joincodes)

WhatsApp offers an API to request a user's location.

<figure><img src="/files/CV3HxdmcYY1gS1hu0m2U" alt="" width="375"><figcaption></figcaption></figure>

<mark style="color:green;">`POST`</mark>&#x20;

```url
https://gateway.lipachat.com/api/v1/whatsapp/request_location
```

**Headers**

| Name         | Value                                                                          |
| ------------ | ------------------------------------------------------------------------------ |
| Content-Type | `application/json`                                                             |
| apiKey       | Get apiKey from App portal settings tab<https://app.lipachat.com/app/settings> |

**Body**

<table><thead><tr><th width="348">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>messageId</td><td>string</td><td>A unique identifier for the message. This will be used to track the message status and for deduplication purposes.</td></tr><tr><td>from</td><td>string</td><td>Sandbox number +254110090747 or your own WABA phone number.</td></tr><tr><td>to</td><td>string</td><td>Receiver phone number. It should start with a country code.</td></tr><tr><td>text</td><td>string</td><td><p>Message body text. Supports URLs.</p><p>Maximum 1024 characters.</p></td></tr></tbody></table>

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

```sh
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/request_location' \
--header 'apiKey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "messageId": "b3e1e37c-e50b-48b2-8972-6cc659ac33d2",
    "to": "2547XXXX",
    "from": "254110090747",
    "text": "Let'\''s start with your pickup. You can either manually *enter an address* or *share your current location*."
}'
```

{% endtab %}

{% tab title="Java" %}

```java
// Create an instance of OkHttpClient
OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

// Define the media type for the request
MediaType mediaType = MediaType.parse("application/json");

// Create the request body with the necessary JSON payload using a text block
RequestBody body = RequestBody.create(mediaType, """
{
    "messageId": "b3e1e37c-e50b-48b2-8972-6cc659ac33d2",
    "to": "2547XXXX",
    "from": "254110090747",
    "text": "Let'\''s start with your pickup. You can either manually *enter an address* or *share your current location*."
}
""");

// Build the request with the required headers
Request request = new Request.Builder()
    .url("https://gateway.lipachat.com/api/v1/whatsapp/request_location")
    .method("POST", body)
    .addHeader("apiKey", "YOUR_API_KEY")
    .addHeader("Content-Type", "application/json")
    .build();

// Execute the request and get the response
Response response = client.newCall(request).execute();



```

{% endtab %}

{% tab title="Javascript" %}

```ruby
const axios = require('axios');
let data = JSON.stringify({
    "messageId": "b3e1e37c-e50b-48b2-8972-6cc659ac33d2",
    "to": "2547XXXX",
    "from": "254110090747",
    "text": "Let'\''s start with your pickup. You can either manually *enter an address* or *share your current location*."
    });

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://gateway.lipachat.com/api/v1/whatsapp/request_location',
  headers: { 
    'apiKey': 'YOUR_API_KEY', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

```

{% endtab %}
{% endtabs %}

**Response**

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

```json
{
      "timestamp": "2023-08-06T01:27:56.825898971",
      "data": {
            "messageId": "7addc006-07db-4fae-aac5-b285903b41d4",
            "waId": "wamid.HBgMMjU0NzE3NzQ2NTY1FQIAEnRgSRjJGRkMzNkQ0QUVENTIxQ0NBAA==",
            "status": "SENT",
            "statusDesc": "Message sent successfully"
      },
      "status": "success",
      "message": "",
      "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
      "timestamp": "2023-08-06T17:50:35.701+00:00",
      "status": 400,
      "error": "Bad Request",
      "path": "/api/v1/whatsapp/request_location"
}
```

{% endtab %}

{% tab title="401" %}

```json
{
      "timestamp": "2023-08-06T20:49:48.455464058",
      "data": null,
      "status": "success",
      "message": "Invalid credentials",
      "errors": null
}
```

{% endtab %}
{% endtabs %}


# Whatsapp Flows

#### Overview

WhatsApp Flows lets you build structured, interactive customer journeys. By defining and customizing messages with rich interactions—such as buttons, checklists, or menus—you can guide customers through a sequence of steps, collect information, and provide relevant options.

**Why Use Flows?**

* Provide a clear, guided experience for users
* Automate information collection (e.g., personal preferences, loan terms)
* Offer product recommendations or quotes
* Seamlessly transition from structured flows to free-form chat

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

## Popular Use Cases

1. **Get Leads for Pre-Approved Loans**
   * Present a configurable loan amount and repayment terms.
   * Let users choose their disbursement and payment options.
   * Securely authenticate to confirm identities.
   * Adaptable for credit card offers, credit limit calculators, loan offers for shopping, and more.
2. **Get an Insurance Quote**
   * Collect personal details (e.g., number of members covered, premium amount, coverage level).
   * Present customizable insurance plans and allow users to pick payment frequency.
   * Easily repurpose for insurance renewals, profile completion, or onboarding.

You can learn more about WhatsApp flows from here: <https://developers.facebook.com/docs/whatsapp/flows/>

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td></td><td>Creating a flow</td><td></td><td><a href="/files/10ev3gAgoidqw7WJrsLe">/files/10ev3gAgoidqw7WJrsLe</a></td><td><a href="/pages/t6wbqekkrHO3gtsSE9rn">/pages/t6wbqekkrHO3gtsSE9rn</a></td></tr><tr><td></td><td>Updating a flow</td><td></td><td><a href="/files/YC8BTkZpyGOjKVsbCJoe">/files/YC8BTkZpyGOjKVsbCJoe</a></td><td><a href="/pages/UjcepfAOoo53VOy6U4WS">/pages/UjcepfAOoo53VOy6U4WS</a></td></tr><tr><td></td><td>Get flow preview</td><td></td><td><a href="/files/GGjFjvln2wzkVEdsXTu7">/files/GGjFjvln2wzkVEdsXTu7</a></td><td><a href="/pages/jjoR2zQJUUvAlQVkpIHM">/pages/jjoR2zQJUUvAlQVkpIHM</a></td></tr><tr><td></td><td>Publish a flow</td><td></td><td><a href="/files/x25a8yKDeTkWyMMySwnK">/files/x25a8yKDeTkWyMMySwnK</a></td><td><a href="/pages/vWVYo9KOr645CAoJi6Bx">/pages/vWVYo9KOr645CAoJi6Bx</a></td></tr><tr><td></td><td>Send a flow</td><td></td><td><a href="/files/xC0C1rwoSiDes8zXWEtP">/files/xC0C1rwoSiDes8zXWEtP</a></td><td><a href="/pages/9IFQ9XNOz0wWLdAAnYuo">/pages/9IFQ9XNOz0wWLdAAnYuo</a></td></tr><tr><td></td><td>List all flows</td><td></td><td><a href="/files/aZOlZ5Foew3QKf3S8mWx">/files/aZOlZ5Foew3QKf3S8mWx</a></td><td><a href="/pages/cK2MKdT95N53q1SeqXfC">/pages/cK2MKdT95N53q1SeqXfC</a></td></tr></tbody></table>


# Creating a flow

```
POST https://gateway.lipachat.com/api/v1/whatsapp/manage/flow
```

**Headers**

| Name         | Value                                                                           |
| ------------ | ------------------------------------------------------------------------------- |
| Content-Type | multipart/form-data                                                             |
| apiKey       | Get apiKey from app portal settings tab <https://app.lipachat.com/app/settings> |

**Body**

| Name        | Type   | Description                                                          |
| ----------- | ------ | -------------------------------------------------------------------- |
| phoneNumber | string | Sandbox number +254110090747 or your own WABA phone number.          |
| name        | string | Name of your flow                                                    |
| categories  | string | Category of the flow: Example: OTHERS                                |
| file        | file   | The file containing your whatsapp flow. File should be of type .json |

**Example Request**

```json
{
  "phoneNumber": "254712345678",
  "name": "BANK_TEST_FLOW_V2",
  "categories": "OTHER",
  "file": "filename.json"
}
```

**Response**

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

```json
{
  "timestamp": "2024-03-12T10:01:04.71248",
  "data": {
    "id": 4,
    "waFlowId": "2044724355999872",
    "name": "BANK_TEST_FLOW_V2",
    "status": "DRAFT",
    "categories": [
      "OTHER"
    ],
    "createdAt": "2024-03-12T07:00:55.887+00:00",
    "updatedAt": "2024-03-12T07:00:58.598+00:00"
   },
  "status": "success",
  "message": "",
  "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "timestamp": "2024-09-15T20:06:38.675567555",
    "data": null,
    "status": "error",
    "message": "Request failed.",
    "errors": null
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "timestamp": "2024-09-15T20:07:23.464199513",
    "data": null,
    "status": "success",
    "message": "Invalid credentials",
    "errors": null
}
```

{% endtab %}
{% endtabs %}


# Updating a flow

NB: ***Once a flow is published it cannot be updated.***

```
PUT https://gateway.lipachat.com/api/v1/whatsapp/manage/flow/:id
NB: Replace :id with the flow id you want to update
```

**Headers**

| Name         | Value                                                                           |
| ------------ | ------------------------------------------------------------------------------- |
| Content-Type | multipart/form-data                                                             |
| apiKey       | Get apiKey from app portal settings tab <https://app.lipachat.com/app/settings> |

**Body**

| Name       | Type   | Description                                                                  |
| ---------- | ------ | ---------------------------------------------------------------------------- |
| name       | string | Name of your flow                                                            |
| categories | string | Category of the flow: Example: OTHERS                                        |
| file       | file   | The file containing your updated whatsapp flow. File should be of type .json |

**Example Request**

```json
{
  "name": "BANK_TEST_FLOW_V2",
  "categories": "OTHER",
  "file": "filename.json"
}
```

**Response**

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

```json
{
  "timestamp": "2024-03-12T10:01:04.71248",
  "data": {
    "id": 4,
    "waFlowId": "2044724355999872",
    "name": "BANK_TEST_FLOW_V2",
    "status": "DRAFT",
    "categories": [
      "OTHER"
    ],
    "createdAt": "2024-03-12T07:00:55.887+00:00",
    "updatedAt": "2024-03-12T07:00:58.598+00:00"
  },
  "status": "success",
  "message": "",
  "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "timestamp": "2024-09-15T20:06:38.675567555",
    "data": null,
    "status": "error",
    "message": "Request failed.",
    "errors": null
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "timestamp": "2024-09-15T20:07:23.464199513",
    "data": null,
    "status": "success",
    "message": "Invalid credentials",
    "errors": null
}
```

{% endtab %}
{% endtabs %}


# Get flow preview

```
GET https://gateway.lipachat.com/api/v1/whatsapp/manage/flow/:id/preview/url
NB: Replace :id with the flow id you want to preview
```

**Headers**

| Name         | Value                                                                           |
| ------------ | ------------------------------------------------------------------------------- |
| Content-Type | application/json                                                                |
| apiKey       | Get apiKey from app portal settings tab <https://app.lipachat.com/app/settings> |

**Response**

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

```json
{
  "timestamp": "2024-03-12T09:59:53.102792",
  "data": {
    "preview": {
      "preview_url": "https://business.facebook.com/wa/manage/flows/1115801529546359/preview/?token=3511a634-cc21-4322-b1d8-7f3abda2dd9d",
      "expires_at": "2024-04-11T06:59:53+0000"
    },
    "id": "1115801529546359"
  },
  "status": "success",
  "message": "",
  "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "timestamp": "2024-09-15T20:06:38.675567555",
    "data": null,
    "status": "error",
    "message": "Request failed.",
    "errors": null
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "timestamp": "2024-09-15T20:07:23.464199513",
    "data": null,
    "status": "success",
    "message": "Invalid credentials",
    "errors": null
}
```

{% endtab %}
{% endtabs %}


# Publish a flow

```
POST https://gateway.lipachat.com/api/v1/whatsapp/manage/flow/:id/publish
NB: Replace :id with the flow id you want to publish
```

**Headers**

| Name         | Value                                                                           |
| ------------ | ------------------------------------------------------------------------------- |
| Content-Type | application/json                                                                |
| apiKey       | Get apiKey from app portal settings tab <https://app.lipachat.com/app/settings> |

**Response**

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

```json
{
  "timestam": "2024-03-12T10:06:27.223053",
  "data": {
    "id": 4,
    "waFlowId": "2044724355999872",
    "name": "BANK_TEST_FLOW_V2",
    "status": "PUBLISHED",
    "categories": [
      "OTHER"
    ],
    "createdAt": "2024-03-12T07:00:55.887+00:00",
    "updatedAt": "2024-03-12T07:06:26.887+00:00"
  },
  "status": "success",
  "message": "",
  "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "timestamp": "2024-09-15T20:06:38.675567555",
    "data": null,
    "status": "error",
    "message": "Request failed.",
    "errors": null
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "timestamp": "2024-09-15T20:07:23.464199513",
    "data": null,
    "status": "success",
    "message": "Invalid credentials",
    "errors": null
}
```

{% endtab %}
{% endtabs %}


# Send a flow

🔒 WhatsApp 24-Hour Session Rule

> Before sending a free-form message, make sure the WhatsApp session with the user is **active**.
>
> **If the user has not messaged your business within the last 24 hours, WhatsApp requires the first message to be a&#x20;*****template message***.
>
> After the customer replies, the 24-hour session opens and you may send free-form messages using this API.\
> **For sandbox testing**, send your join code to the sandbox number to activate your session.\
> [Learn more](https://app.gitbook.com/o/rJyj7TfON4zeW56KoQjM/s/2JHt6V4YwZLX6ZUdLqMy/~/changes/87/guides/joincodes)

```shellscript
POST https://gateway.lipachat.com/api/v1/whatsapp/interactive/flows
```

**Header**

| Name         | Value                                                                           |
| ------------ | ------------------------------------------------------------------------------- |
| Content-Type | application/json                                                                |
| apiKey       | Get apiKey from app portal settings tab <https://app.lipachat.com/app/settings> |

**Body**

| Name               | Type   | Description                                                                                                        |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------ |
| messageId          | string | A unique identifier for the message. This will be used to track the message status and for deduplication purposes. |
| to                 | string | PhonReceiver phone number. It should start with a country code.                                                    |
| from               | string | Sandbox number +254110090747 or your own WABA phone number.                                                        |
| text               | string |                                                                                                                    |
| flowId             | string | Id of the flow you want to send                                                                                    |
| flowCta            | string | Text to appear on the submit button of the flow                                                                    |
| screen             | string | First screen of your json request/flow                                                                             |
| data.service       | string |                                                                                                                    |
| data.serviceOption | string |                                                                                                                    |
| data.package       | string |                                                                                                                    |

**Example Request**

```json
{
  "messageId": "{{$randomUUID}}",
  "to": "254717746565",
  "from": "{{SANDBOX_NUMBER}}",
  "text": "Thank you share your details and one of our agents will be in touch",
  "flowId": "YOUR_FLOW_ID",
  "flowCta": "Share Details!",
  "screen": "First screen in your JSON request",
  "data": {
    "service": "",
    "serviceOption": "",
    "package": ""
  }
}
```

**Response**

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

```json
{
  "timestamp": "2024-03-22T11:42:18.625016916",
  "data": {
    "messageId": "1a85c604-0f08-4182-8011-407ba84598c5",
    "waId": "wamid.HBgMMjU0NzE3NzQ2NTY1FQIAERgSMDUxNjI2OEE5OUUyMzQzMjM4AA==",
    "status": "SENT",
    "statusDesc": "Message sent successfully"
  },
  "status": "success",
  "message": "",
  "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "timestamp": "2024-09-15T20:06:38.675567555",
    "data": null,
    "status": "error",
    "message": "Request failed.",
    "errors": null
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "timestamp": "2024-09-15T20:07:23.464199513",
    "data": null,
    "status": "success",
    "message": "Invalid credentials",
    "errors": null
}
```

{% endtab %}
{% endtabs %}


# List all flows

```
GET https://gateway.lipachat.com/api/v1/whatsapp/manage/flow?per_page=10&page=1
```

**Headers**

| Name         | Value                                                                           |
| ------------ | ------------------------------------------------------------------------------- |
| Content-Type | application/json                                                                |
| apiKey       | Get apiKey from app portal settings tab <https://app.lipachat.com/app/settings> |

**Response**

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

```json
{
  "data": [
    {
      "id": 1,
      "waFlowId": "1115801529546350",
      "name": "TEST_FLOW_V1",
      "status": "DRAFT",
      "categories": [
        "OTHER"
      ],
      "createdAt": "2024-03-12T06:38:08.380+00:00",
      "updatedAt": "2024-03-12T06:38:11.771+00:00"
    }
  ],
  "totalPages": 1,
  "totalItemsInPage": 1,
  "totalElements": 1
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "timestamp": "2024-09-15T20:06:38.675567555",
    "data": null,
    "status": "error",
    "message": "Content in this language already exists",
    "errors": null
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "timestamp": "2024-09-15T20:07:23.464199513",
    "data": null,
    "status": "success",
    "message": "Invalid credentials",
    "errors": null
}
```

{% endtab %}
{% endtabs %}


# Webhooks

## Overview

This section explains how to set up webhook endpoints to receive:

* Inbound Messages (text, media, interactive, etc.)
* Optional Message Status Updates (e.g., delivered, read, failed)

Having both webhooks enabled ensures you can process incoming customer messages and track the lifecycle of messages you send.

## Inbound Message Webhooks

#### Configuring the Inbound Webhook

{% stepper %}
{% step %}
**Navigate to Settings**

In your application or developer dashboard, set the **Inbound Webhook URL** (e.g., `https://example.com/webhook/whatsapp/inbound`).
{% endstep %}

{% step %}
**Receive Webhooks**

All incoming WhatsApp messages (new messages and replies) will trigger a POST to your inbound webhook URL.
{% endstep %}
{% endstepper %}

#### Supported Inbound Message Types

Inbound messages can contain various content types:

* Text
* Media (image, video, audio, document)
* Sticker
* Location
* Contact
* Interactive
  * List response
  * Button response

Check the `type` field in the webhook payload to determine what the user has sent.

#### Sample Webhooks Incoming Messages

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

```json
{
     "messageId": "c94ced08-5f40-46b7-a88d-7d4fbe113fe9",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "TEXT",
     "text": "Text Content"
}
```

{% endtab %}

{% tab title="Image" %}

```json
{
     "messageId": "c94ced08-5f40-46b7-a88d-7d4fbe113fe9",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "IMAGE",
     "image": {
          "caption": null,
          "url": "HTTPS URL"
     }
}
```

{% endtab %}

{% tab title="Video" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "VIDEO",
     "video": {
          "caption": null,
          "url": "HTTPS URL"
     }
}
```

{% endtab %}

{% tab title="Audio" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "AUDIO",
     "audio": {
          "caption": null,
          "url": "HTTPS URL"
     }
}
```

{% endtab %}

{% tab title="Document" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "DOCUMENT",
     "document": {
          "caption": null,
          "url": "HTTPS URL"
     }
}
```

{% endtab %}
{% endtabs %}

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

```json
{
     "to": "",
     "from": "",
     "type": "LOCATION",
     "location": {
          "name": "",
          "address": "Kiambu Road",
          "latitude": "",
          "longitude": ""
     },
     "messageId": "WA_MESSAGE_ID",
     "profileName": "CUSTOMER_NAME"
}
```

{% endtab %}

{% tab title="Contact" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "CONTACTS",
     "contacts": [
          {
               "addresses": null,
               "birthday": null,
               "emails": null,
               "name": {
                    "suffix": null,
                    "prefix": null,
                    "formatted_name": "",
                    "first_name": "",
                    "last_name": "",
                    "middle_name": null
               },
               "org": null,
               "phones": [
                    {
                         "phone": "PHONE NUMBER",
                         "type": "MOBILE",
                         "wa_id": "PHONE NUMBER"
                    }
               ],
               "urls": null
          }
     ]
}
```

{% endtab %}

{% tab title="Sticker" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "STICKER",
     "sticker": {
          "caption": null,
          "url": "HTTPS URL"
     }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Interactive List" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "INTERACTIVE",
     "interactive": {
          "type": "list_reply",
          "list_reply": {
               "id": "NAIROBI_WATER",
               "title": "Nairobi Water"
          }
     }
}
```

{% endtab %}

{% tab title="Interactive Buttons" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "INTERACTIVE",
     "interactive": {
          "type": "button_reply",
          "button_reply": {
               "id": "1",
               "title": "YES"
          }
     }
}
```

{% endtab %}
{% endtabs %}

## Message Status Callbacks

#### What Are Status Callbacks?

When you send a message or manage a template, our service can notify your application of changes via HTTP POST requests to a separate webhook URL. There are two main categories:

* Message Delivery Status: Track whether your outbound message was sent, delivered, read, or failed.
* Template Status: Track changes in your message template approval status (e.g., approved, rejected, paused).

#### Configuring Status Callbacks

&#x20;Navigate to Settings: Set the Status Callback URL (e.g.,`https://example.com/webhook/whatsapp/status`).

Possible status values include:

* SENT
* DELIVERED
* READ
* DELETED
* FAILED

#### Sample JSON: Message Delivery Status

```json
{
     "event": "MESSAGE_STATUS",
     "messageStatus": {
          "waId": "",
          "messageId": "",
          "conversationId": "",
          "status": "DELIVERED",
          "statusDesc": "",
          "timestamp": 1749062767
     }
}
```

For outbound messages, the <mark style="color:blue;">**messageId**</mark> corresponds to the ID included in the request

## Template Status Updates

We also send callbacks when your WhatsApp message templates change status. Possible status values include:

* **APPROVED**: The template is approved and ready for use.
* **REJECTED**: The template has been denied—check for policy violations.
* **PAUSED**: The template is temporarily suspended, often pending manual review.

statusDescription will contain the reason why a template has been rejected or paused.

**Sample JSON: Template Status Update**

```json
{
     "event": "TEMPLATE_STATUS",
     "templateStatus": {
          "status": "APPROVED",
          "templateId": "",
          "templateName": "",
          "statusDescription": ""
     }
}
```


# OpenAPI

You can sync GitBook pages with an OpenAPI or Swagger file or a URL to include auto-generated API methods in your documentation.

### OpenAPI block

GitBook's OpenAPI block is powered by [Scalar](https://scalar.com/), so you can test your APIs directly from your docs.

{% openapi src="<https://petstore3.swagger.io/api/v3/openapi.json>" path="/pet" method="post" %}
<https://petstore3.swagger.io/api/v3/openapi.json>
{% endopenapi %}


# Integrations

GitBook integrations allow you to connect your GitBook spaces to some of your favorite platforms and services. You can install integrations into your GitBook page from the *Integrations* menu in the top left.

<figure><img src="https://gitbookio.github.io/onboarding-template-images/integrations-hero.png" alt=""><figcaption></figcaption></figure>

### Types of integrations

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden></th></tr></thead><tbody><tr><td><strong>Analytics</strong></td><td>Track analytics from your docs</td><td><a href="https://www.gitbook.com/integrations#analytics">https://www.gitbook.com/integrations#analytics</a></td><td><a href="/files/vxs1ER5I8VkIA0IaOqfo">/files/vxs1ER5I8VkIA0IaOqfo</a></td><td></td></tr><tr><td><strong>Support</strong></td><td>Add support widgets to your docs</td><td><a href="https://www.gitbook.com/integrations#support">https://www.gitbook.com/integrations#support</a></td><td><a href="/files/WqTZslyWgLz3XWQj63oY">/files/WqTZslyWgLz3XWQj63oY</a></td><td></td></tr><tr><td><strong>Interactive</strong></td><td>Add extra functionality to your docs</td><td><a href="https://www.gitbook.com/integrations#interactive">https://www.gitbook.com/integrations#interactive</a></td><td><a href="/files/SdPaDKIKifbvNn0jWHM0">/files/SdPaDKIKifbvNn0jWHM0</a></td><td></td></tr><tr><td><strong>Visitor Authentication</strong></td><td>Protect your docs and require sign-in</td><td><a href="https://www.gitbook.com/integrations#visitor-authentication">https://www.gitbook.com/integrations#visitor-authentication</a></td><td><a href="/files/UHF7zjwcq36zmrwja3ub">/files/UHF7zjwcq36zmrwja3ub</a></td><td></td></tr></tbody></table>


# Sandbox

If you’re looking to build a WhatsApp Chatbot, CRM integration, or marketing campaign, the first step is to try out our **Sandbox Environment**.

The sandbox allows you to test sending and receiving WhatsApp messages without needing your own WhatsApp Business Number. It's a great way to validate your setup and understand our APIs.

### What is the Sandbox?

The sandbox is a test WhatsApp number provided by Lipachat. You can:

* Send business-initiated messages
* Receive and reply to messages
* Test webhooks
* Build and test chatbots
* Run CRM-like flows
* Simulate surveys and broadcasts

No approvals or number setup is needed—just connect and test.

### 🚀 Step-by-Step: Connect to the Sandbox

#### 1. Join the Sandbox

Send the code below to our sandbox number to activate your 24-hour session:

{% hint style="info" %}
Your session is valid for 24 hours. To keep using the sandbox, you must send a message within that window to extend it.
{% endhint %}

2. #### Send a Message via API

Once connected, you can send a message using our [Message API](/api/sending-messages).

Sample Request:

```sh
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/message/text' \
--header 'apiKey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "message": "Hello world",
    "messageId": "e66fc7b8-680f-4887-8dc8-ee062d65b54f",
    "to": "254XXXXXXX",
    "from": "254110090747"
}'
```

You can also explore prebuilt examples in our [Postman Collection](https://www.postman.com/lively-shuttle-345383/workspace/lipachat-apis/collection/1880882-362c9de0-8bff-4dbb-9596-194223a41ad8?action=share\&creator=1880882\&active-environment=1880882-199aa005-02f1-4f12-8b08-70ab6d90d1ee)

### Common Troubleshooting

<table><thead><tr><th width="294.39453125">Problem</th><th>Solution</th></tr></thead><tbody><tr><td>401 Unathorized</td><td>Ensure you are sending apiKey header.</td></tr><tr><td>400 No active sanbox session</td><td>Check if you are within the 24-hour window or if the number was entered correctly.</td></tr><tr><td>Webhook not firing</td><td>Double-check your webhook URL configuration and use webhook.site to test.</td></tr></tbody></table>


# Go Live

Once you've tested your chatbot, CRM, or campaign using our Sandbox, you're ready to move to **Production**. This process involves connecting your own WhatsApp Business number using Meta's Embedded Signup.

### 🚀 Steps to Go Live

#### 1. Prepare Your Business

Before you begin, make sure you have:

* A **Facebook Business Manager** account
* Admin access to that Business Manager
* A **verified phone number** (not linked to any other WhatsApp Business account)
* A display name that complies with WhatsApp's guidelines

#### 2. Start the Meta Embedded Signup

Click the button below to begin the Meta signup process:

🔗 [Start WhatsApp Embedded Signup](https://app.lipachat.com/app/golive)

During the flow, you'll:

* Select a business or add a business in Facebook Business Manager
* Add your phone number
* Verify the number via SMS or voice call
* Approve Lipachat as your WhatsApp Business Solution Provider (BSP)

#### 3. Configure Webhooks

After a successful number setup, you'll be redirected to Lipachat to:

* Set up your webhook URL
* Test a sample message

Use tools like [webhook.site](https://webhook.site) to test webhook delivery before plugging into your system.

#### 4. Approve Message Templates

To send **business-initiated messages**, you must:

* Create templates in the Lipachat Dashboard
* Submit for approval by Meta (usually takes a few minutes)

Once approved, you can:

* Send messages outside the 24-hour session window
* Launch campaigns and notifications

5. #### You're Live!

You can now:

* Receive real messages from your customers
* Send broadcast campaigns
* Run your chatbot or CRM in production


# Template Review & Approval

### Approval Criteria

WhatsApp may **reject** a template if any of the following apply:

* **Invalid format**: missing, misplaced, or malformed placeholders.
* **Policy violations**: content conflicts with WhatsApp Terms/Business/Commerce policies.
* **Too generic**: lacks context or looks like it could be misused.

### Template Statuses

* **Pending** — Under automated review and/or manual review (may take up to 48 hours).
* **Approved** — Ready to use; messages can be sent to customers.
* **Rejected** — Not approved during review (see common fixes below).
* **Paused** — Temporarily halted due to negative user feedback (e.g., blocks/spam reports); cannot be used while paused.
* **Disabled** — Permanently blocked due to repeated negative feedback or a policy violation; cannot be used.

### &#x20;Common Rejection Reasons & How to Fix

| Reason                                                            | How to fix                                                                 |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Variable at the very start or end of the message                  | Add static text or punctuation before/after the variable                   |
| Adjacent variables (e.g., {{1}}{{2}})                             | Add at least one word/symbol between them, or merge into a single variable |
| Non-sequential variable numbers (e.g., {{1}}, {{2}}, {{4}})       | Make variables sequential ({{1}}, {{2}}, {{3}}…)                           |
| Duplicates another template (name-only change)                    | Change both the name and the message content                               |
| Contains gaming/gambling language (e.g., “raffle”, “win a prize”) | Replace with neutral wording that avoids gaming/gambling terms             |
| Overly vague (e.g., “Hi, {{1}}, thanks”)                          | Add clear context and purpose so reviewers see intended use                |
| Language doesn’t match content                                    | Select the correct language for the message text                           |
| More than 10 emojis                                               | Reduce emojis to 10 or fewer                                               |

### Template Categorization (pick the correct type)

See Meta’s guidelines: [New Template Guidelines](https://developers.facebook.com/docs/whatsapp/updates-to-pricing/new-template-guidelines/?utm_source=chatgpt.com)

**Utility**&#x20;

Service/transactional updates the user expects.

* *Examples*:
  * “Your order **#{{1}}** was delivered on **{{2}}**.”
  * “Your appointment on **{{1}}** at **{{2}}** is confirmed.”
  * “Payment **{{1}}** received. View receipt: **{{2}}**.”

**Authentication**

Messages that deliver one-time passcodes.

* *Examples*:

  * “Your verification code is **{{1}}**. It expires in **{{2}}** minutes.”
  * “Use **{{1}}** to confirm your login on **{{2}}**.”

Marketing

Promotional or engagement messages intended to drive action (offers, new products, win-backs, reminders to complete a purchase).

* **Examples**
  * “New offer: **{{1}}** off **{{2}}**. Shop now: **{{3}}**.”
  * “Back in stock: **{{1}}**. Tap to buy: **{{2}}**.”
  * “You left **{{1}}** in your cart. Complete your order: **{{2}}**.”
  * “Exclusive launch for you, **{{1}}**. Learn more: **{{2}}**.”
* **Best practices**
  * Obtain user **opt-in** before sending marketing messages. [Facebook Developers](https://developers.facebook.com/docs/whatsapp/overview/getting-opt-in/?utm_source=chatgpt.com)
  * Consider adding an **opt-out** quick reply (e.g., “Stop promotions”) to reduce spam reports and keep quality high. (Some platforms expose a “marketing opt-out” option in the template builder.)
  * Meta may apply **per-user marketing template limits** and different pricing/handling vs. Utility/Auth.

> **Tip:** Keep variables only for the parts that truly change (names, times, codes, order IDs). Avoid starting or ending the message with a variable, avoid fully dynamic URLs, and always include realistic **sample values** when submitting.


# Build A Chat Bot

This guide walks you through setting up a basic WhatsApp chatbot using Lipachat APIs. It assumes you’ve already joined the sandbox or connected your own WhatsApp Business number.

### 🪝 Step 1: Set Up Your Webhook

Navigate to the Lipachat Dashboard → **Settings** → **Webhook**

Set the **Webhook URL** to point to your server endpoint that will handle incoming messages.

**Example:**

```
https://yourdomain.com/webhook
```

When a customer sends a message on WhatsApp, Lipachat will send a POST request to your webhook with the message payload.

### 📩 Step 2: Handle Incoming Message

Example payload:

```json
{
     "messageId": "c94ced08-5f40-46b7-a88d-7d4fbe113fe9",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "TEXT",
     "text": "Text Content"
}
```

Your backend logic should parse this payload and determine the appropriate response (e.g., predefined replies or bot logic).

### 📤 Step 3: Respond with a Message

Once your bot determines a reply, call the [**Free-Form Message API**](/api/sending-messages) to respond.

**Text reply example:**

```shellscript
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/message/text' \
--header 'apiKey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "message": "Hello world",
    "messageId": "e66fc7b8-680f-4887-8dc8-ee062d65b54f",
    "to": "254XXXXXXX",
    "from": "254110090747"
}'
```

### 🖼 Optional: Respond with Media

Use the **Send Media API** to reply with images, PDFs, audio, or video.

**Media reply example:**

```shellscript
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/media' \
--header 'apiKey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "messageId": "5d3f62c3-eb8f-4150-8941-bdceb0f429bb",
    "to": "254XXXXX",
    "from": "254110090747",
    "mediaType": "IMAGE",
    "mediaUrl": "https://picsum.photos/id/237/200/300",
    "caption": ""
}'
```

Other supported message types are: Buttons, Interactive Lists, Contacts, Location, and Flows.

### Summary: End-to-End Flow

1. The customer sends a message via WhatsApp
2. Lipachat delivers the message to your **Webhook**
3. Your chatbot processes the message
4. Your system calls `Send Message` or `Send Media` API
5. The customer receives the bot reply on WhatsApp


# Join code

* Found on your Lipachat app [dashboard](https://app.lipachat.com/app/home).
* Used only in **sandbox mode** to test the WhatsApp API end-to-end before linking your own number.
* Once your number is linked, you won’t need join codes.

**Active Sessions**

* WhatsApp requires an **active 24-hour session** to send messages (text, media, buttons).
* A session is created when you send a message to:
  * The **sandbox number** (using your join code), or
  * Your own WhatsApp number once it’s linked.
* If you don’t want the customer to send the first message, you can send messages by using a **pre-approved template**.

**How to Get Your Joincode**

1. Log in to [app.lipachat.com](https://app.lipachat.com).
2. Navigate to the **Home** screen.
3. Your join code is displayed there (see example below).

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

**How to Start a 24-Hour Session**

* On your WhatsApp mobile app, send your join code to the sandbox number.
* Example: if your join code is `elipa`, send:

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

* This will create a session, after which you can send any type of message.


# Sending Broadcast Messages

Broadcasts allow you to send a WhatsApp message to many customers at once using a **WhatsApp-approved template**.

> **Free-form vs Templates**\
> WhatsApp requires message templates for any business-initiated communication that occurs outside of an active session. A session automatically begins whenever a user sends a message to your WhatsApp number and remains open for 24 hours. During an active session, you can exchange free-form messages without additional constraints.

***

### Broadcast Flow Overview

1. **Verify the template exists**, or create it if missing
2. **Loop through your recipients** and send the template via API
3. **Receive customer replies** through the Incoming Messages Webhook
4. **Receive delivery/read status** through the Status Webhook

### 1. Verify or Create a Template

Before broadcasting, make sure the template already exists in your Lipachat workspace.

If missing, create a new template via:

🔗 **Creating a Template**\
<https://docs.lipachat.com/api/editor/creating-a-template>

Template approval is handled by Meta and is **automated**, typically completing **within 5 minutes**.

**Example template content:**

```
Dear {{1}} we have an offer for you this Black Friday {{2}}
```

Placeholders (`{{1}}`, `{{2}}`) will be replaced using your request payload.

***

### 2. Sending the Template to Multiple Customers

Use the Template Send API endpoint:

🔗 **Send Template**\
<https://docs.lipachat.com/api/editor/send-template>

API URL used for sending:

```
POST https://gateway.lipachat.com/api/v1/whatsapp/template
```

#### Example Request Payload

```json
{
  "messageId": "d13ce19b-678f-4a94-a910-441cfbb25b9b",
  "to": "PHONE_NUMBER",
  "from": "BUSINESS_PHONE_NUMBER",
  "template": {
    "name": "offer_830",
    "languageCode": "en",
    "components": {
      "header": {
        "type": "TEXT",
        "parameter": "Discounts"
      },
      "body": {
        "placeholders": [
          "John",
          "https://shop.com/offer123"
        ]
      }
    }
  }
}
```

***

#### JavaScript Example: Looping Through Recipients

Below is a simple Node.js script that:

* Reads a list of `{ phone, name, link }`
* Replaces `{{1}}` with the customer’s name
* Replaces `{{2}}` with their personalised link
* Sends the template message to each contact

```javascript
import fetch from "node-fetch";

const API_KEY = "YOUR_LIPACHAT_API_KEY";
const API_URL = "https://gateway.lipachat.com/api/v1/whatsapp/template";

const recipients = [
  { phone: "+254700000001", name: "Mary", link: "https://shop.com/bf1" },
  { phone: "+254700000002", name: "James", link: "https://shop.com/bf2" },
  { phone: "+254700000003", name: "Aisha", link: "https://shop.com/bf3" }
];

async function sendTemplateMessage(recipient) {
  const payload = {
    messageId: crypto.randomUUID(),
    to: recipient.phone,
    from: "YOUR_WHATSAPP_NUMBER",
    template: {
      name: "black_friday_offer",
      languageCode: "en",
      components: {
        header: {
          type: "TEXT",
          parameter: "Black Friday Offer"
        },
        body: {
          placeholders: [
            recipient.name,  // {{1}}
            recipient.link   // {{2}}
          ]
        }
      }
    }
  };

  const response = await fetch(API_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY
    },
    body: JSON.stringify(payload)
  });

  const result = await response.json();
  console.log(`Sent to ${recipient.phone}:`, result);
}

async function sendBroadcast() {
  for (const r of recipients) {
    try {
      await sendTemplateMessage(r);
    } catch (err) {
      console.error(`Failed to send to ${r.phone}`, err);
    }
  }
}

sendBroadcast();
```

***

### 3. Receiving Customer Replies

When a customer responds to your broadcast, Lipachat immediately sends the message payload to your Incoming Messages Webhook.

Refer to:

🔗 **Webhooks Reference**\
<https://docs.lipachat.com/api/webhooks>

#### Example Incoming Message Payload

```json
{
  "messageId": "c94ced08-5f40-46b7-a88d-7d4fbe113fe9",
  "from": "CUSTOMER_PHONE_NUMBER",
  "to": "WHATSAPP_NUMBER",
  "profileName": "CUSTOMER_NAME",
  "type": "TEXT",
  "text": "I am interested in this product, do you offer delivery services"
}
```

Use this data to:

* Track customer interest
* Register opt-outs (STOP, CANCEL, etc.)
* Trigger workflows (e.g., assign agent, create order, qualify lead)

***

### 4. Receiving Delivery & Read Status

As WhatsApp processes your outbound messages, Lipachat will send status updates to your Status Webhook.

Refer to:

🔗 **Webhooks Reference**\
<https://docs.lipachat.com/api/webhooks>

Common statuses:

* `delivered`
* `read`
* `failed`

These events allow you to build reporting dashboards or retry failed messages.

***

### Best Practices

* Ensure each recipient has all required placeholders before sending.
* For large lists, batch sends to avoid rate limiting.
* Log all incoming messages + statuses for analytics.
* Immediately honor STOP/opt-out replies.


# CRM Workflow

🧑‍💼 Integrate a CRM Workflow with WhatsApp

This tutorial guides you through integrating a CRM system with Lipachat to allow operators to respond to WhatsApp messages in real time. It includes logic for handling both 24-hour session replies and template-based messages.

### 🪝 Step 1: Set Up Webhook

Set your webhook endpoint in the Lipachat Dashboard → **Settings**. This allows Lipachat to notify your CRM when a customer sends a WhatsApp message.

**Example:**

```
https://yourcrm.com/api/whatsapp-webhook
```

When a message is received, a POST request will be made to this URL with the message details.

### 📥 Step 2: Receive and Display Incoming Messages

**Sample webhook payload:**

```json
{
     "messageId": "c94ced08-5f40-46b7-a88d-7d4fbe113fe9",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "TEXT",
     "text": "Text Content"
}
```

Display the message in your CRM’s chat interface and associate it with the appropriate customer profile.

### 🧠 Step 3: Determine Session Status

Check whether the 24-hour session window is still valid. If the current timestamp is **before** `session_expires_at`, respond with a free-form message. Otherwise, use a pre-approved template.

```
const isSessionActive = Date.now() < session_expires_at;
```

{% hint style="info" %}
Session expires at should hold the timestamp of the last message time + 24 hours.\
E.g., if a customer's last message is 27th May 2025 9.00 am, the 'session\_expires\_at' will be 28th May 2025 9.00 am
{% endhint %}

### 📝 Step 4A: Respond Within 24-Hour Session (Free Form)

```sh
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/message/text' \
--header 'apiKey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "message": "Hello, how can I help you today?",
    "messageId": "e66fc7b8-680f-4887-8dc8-ee062d65b54f",
    "to": "254XXXXXXX",
    "from": "254110090747"
}'
```

### 🧾 Step 4B: Respond Outside Session (Template Message)

```sh
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/template' \
--header 'apiKey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
	"messageId": "5c7be224-be61-4aa5-97aa-98906f1f6d15",
	"to": "254XXXXXXX",
	"from": "254110090747",
	"template": {
		"name": "declined_transfert",
		"languageCode": "en",
		"components": {
			"header": {
				"type": "IMAGE", 
				"mediaUrl": "https://picsum.photos/id/237/200/300" 
			},
			"body": {
				"placeholders": [
					"John",
					"Airtime",
					"KES 100",
					"Insufficient funds",
					"funding your account"
				]
			}
		}
	}
}'
```

### End-to-End Flow Summary

1. Customer sends message → webhook sends to CRM
2. CRM operator sees message and session info
3. If the session is active → send a reply
4. If the session expired → send the approved template

With this setup, your CRM team can interact with customers compliantly and in real time via WhatsApp.

Need help creating message templates? Visit the [Message Templates](/api/templates) Guide.