# Custom Events

***

## Introduction

All events apart from Shopify Events are considered Custom Events. These events could be from third-party tools, logistic partners, checkout partners, etc.

***

## How to receive custom events?

The Custom Events API allows clients to stream their unique events to our server. Upon receiving these events, the server can trigger corresponding workflows based on the specific event and associated data.

#### Endpoint

```
POST <https://flow-builder.limechat.ai/api/v1/cvf-events>
```

#### Headers

* `Content-Type: application/json`
* `x-limechat-uat: <access_token>`

  You can go to your profile settings: <https://outbound.limechat.ai/app/settings/profile> and click on the generate new key in case you don’t already have one. The “New API Key” section displays your access token

  \<aside> 💡 Please keep this token somewhere safe as it won’t be visible again.

  \</aside>

  ![Untitled](https://prod-files-secure.s3.us-west-2.amazonaws.com/7a099a4b-9d25-4c8c-8175-4ea980187a7e/b7217ff6-1016-4e22-b9fb-00e65418b26b/Untitled.png)
* `x-fb-account-id:<account_id>`

  It can be found in the account settings: <https://outbound.limechat.ai/app/settings/account>. The Id section displays the account\_id.

  ![Untitled](https://prod-files-secure.s3.us-west-2.amazonaws.com/7a099a4b-9d25-4c8c-8175-4ea980187a7e/3f81fa6f-336d-468e-a60b-0e8f6f7252f6/Untitled.png)

#### Body Parameters

* `distinct_id`: A unique identifier for the user on the client's system. If no distinct ID is available, the `phone` parameter can be used as the `distinct_id`.
* `phone`: The user's phone number. It must include the country code.
* `event`: The name of the event that occurred.
* `data`: A JSON object containing additional data related to the event. This can include any kind of key-value pairs.

\<aside> 💡 It is recommended that you send `event` without any spaces, as some functionality might not work for events that have spaces. `MyAwesomeEvent` Good `My Awesome Event` Bad `My_Awesome_Event` Good `my_awesome_event` Great

\</aside>

Here is an example request:

```bash
curl --location '<https://flow-builder.limechat.ai/api/v1/cvf-events>' \\
--header 'Content-Type: application/json' \\
--header 'x-limechat-uat: <token>' \\
--header 'x-fb-account-id: <account_id>' \\
--data '{
    "distinct_id": "915673412780",
    "phone": "+915673412780",
    "event": "product_view",
    "data": {
        "product_id": "65432",
        "product_name": "Cool Sneakers",
        "category": "Footwear",
        "currency": "INR"
    }
}'
```

In the above example, the event being sent is `product_view`. The `data` field includes additional information about the event.

***

## Examples

**Order Placement Event**: When a user places an order.

```bash
curl --location '<https://flow-builder.limechat.ai/api/v1/cvf-events>' \\
--header 'Content-Type: application/json' \\
--header 'x-limechat-uat: <token>' \\
--header 'x-fb-account-id: <account_id>' \\
--data '{
    "distinct_id": "915673412780",
    "phone": "+915673412780",
    "event": "order_placed",
    "data": {
        "order_id": "98765",
        "total_amount": "$199",
        "products": [{"product_id": "12345", "quantity": 2}, {"product_id": "67890", "quantity": 1}]
        "currency": "INR"
    }
}'

```

Here's an example where a user completes a survey:

```bash
curl --location '<https://flow-builder.limechat.ai/api/v1/cvf-events>' \\
--header 'Content-Type: application/json' \\
--header 'x-limechat-uat: <token>' \\
--header 'x-fb-account-id: <account_id>' \\
--data '{
    "distinct_id": "915673412780",
    "phone": "+915673412780",
    "event": "survey_completion",
	    "data": {
        "survey_id": "54321",
        "completion_time": "15 minutes",
        "user_feedback": "Great survey!",
        "survey_score": "90"
    }
}'

```

In this case, the `event` is `survey_completion`, and the `data` field contains information about the survey ID, the time taken to complete the survey, user feedback, and the score obtained in the survey.

***