# 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.

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://limechatai.gitbook.io/limechat-product-guide/whatsapp-marketing/flows/events/custom-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.