# Webhooks

## Incoming webhook

An incoming webhook lets you use the conversational AI and intent detection in a platform of your choice. You can start conversations and Ebbot will try to match the phrase with a scenario and respond with a proper answer. 

Follow the instructions below to add an incoming webhook

1. Head to the webhook page in the integrations section in the left sided menu.
2. Click on add and then choose incoming as the type
3. Give the webhook a name 
4. Click on save

### Send a request

Once you have the webhook URL you only need to make a post request to that URL to start the conversation. You can run the conversation in sandbox mode which means that it will not be created in the conversations table. The bot will still respond as in a regular conversation. 

On the first request that isn't in sandbox mode you will receive a chat id that should be use if you like to continue the conversation with the same id. It's required if you would like to use context and be able to answer on follow-up questions.  If you don't pass the chat id a new conversation will be started for each request. 

<mark style="color:green;">`POST`</mark> `https://v2.ebbot.app/api/webhooks/:webhookid`

#### Request Body

| Name   | Type   | Description                             |
| ------ | ------ | --------------------------------------- |
| chatId | string | To continue on an existing conversation |
| type   | string | The type of the message                 |
| value  | string | The message to be sent                  |

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

```javascript
{
    "request_id": "197d7397-bf87-4740-a829-ea7251bff534",
    "data": {
        "chatId": "1613384238.420.50c9b6c7-96b6-4794-b09f-3ac7ae27c598",
        "sandbox": false,
        "scenario": {
            "id": "e67494b0-6c9c-11eb-aed8-d37ca2e276ae_e881fbe7-792a-479b-8cfd-848f91120e9c",
            "name": "generalcatchall"
        },
        "answers": [
            {
                "id": "c780c560-c191-4368-924c-57a491dc1748",
                "name": "generalcatchallask",
                "bot_id": "ebmjx2zgfh06t4sxtxko6dcst66w4q",
                "botId": "ebmjx2zgfh06t4sxtxko6dcst66w4q",
                "companyId": "eb8ag1gmiktma952j949arkwu6l93v",
                "parameters": {},
                "db": {},
                "conversation": {},
                "customer_info": {
                    "first_name": "Reluctant",
                    "last_name": "Snake"
                },
                "chatId": "1613384238.420.50c9b6c7-96b6-4794-b09f-3ac7ae27c598",
                "sender": "user",
                "type": "url",
                "value": {
                    "description": "Would you like to talk with a human agent?",
                    "urls": [
                        {
                            "id": "1652c631-a7f5-45a2-a84f-072809631208",
                            "label": "Yes",
                            "type": "scenario",
                            "next": {
                                "scenario": "e656fa90-6c9c-11eb-aed8-d37ca2e276ae_29029c56-4b82-454e-ad75-12445beae6c4"
                            }
                        },
                        {
                            "id": "ae5f4cd7-9734-4369-b8c9-dd5ca476e5af",
                            "label": "No",
                            "type": "scenario"
                        }
                    ]
                }
            }
        ]
    },
    "success": true
}
```

{% endtab %}
{% endtabs %}

#### Example request

```javascript
{
    "type": "text",
    "sandbox": false,
    "value": "Hello there"
}
```

#### Example response

```javascript
{
    "request_id": "197d7397-bf87-4740-a829-ea7251bff534",
    "data": {
        "chatId": "1613384238.420.50c9b6c7-96b6-4794-b09f-3ac7ae27c598",
        "sandbox": false,
        "scenario": {
            "id": "e67494b0-6c9c-11eb-aed8-d37ca2e276ae_e881fbe7-792a-479b-8cfd-848f91120e9c",
            "name": "generalcatchall"
        },
        "answers": [
            {
                "id": "c780c560-c191-4368-924c-57a491dc1748",
                "name": "generalcatchallask",
                "bot_id": "ebmjx2zgfh06t4sxtxko6dcst66w4q",
                "botId": "ebmjx2zgfh06t4sxtxko6dcst66w4q",
                "companyId": "eb8ag1gmiktma952j949arkwu6l93v",
                "parameters": {},
                "db": {},
                "conversation": {},
                "customer_info": {
                    "first_name": "Reluctant",
                    "last_name": "Snake"
                },
                "chatId": "1613384238.420.50c9b6c7-96b6-4794-b09f-3ac7ae27c598",
                "sender": "user",
                "type": "url",
                "value": {
                    "description": "Would you like to talk with a human agent?",
                    "urls": [
                        {
                            "id": "1652c631-a7f5-45a2-a84f-072809631208",
                            "label": "Yes",
                            "type": "scenario",
                            "next": {
                                "scenario": "e656fa90-6c9c-11eb-aed8-d37ca2e276ae_29029c56-4b82-454e-ad75-12445beae6c4"
                            }
                        },
                        {
                            "id": "ae5f4cd7-9734-4369-b8c9-dd5ca476e5af",
                            "label": "No",
                            "type": "scenario"
                        }
                    ]
                }
            }
        ]
    },
    "success": true
}
```

### Set a variable

If you have triggered a scenario that contains buttons with variables you set the type to variable and then pass the clicked variable button to the value property.

```javascript
{
    "type": "variable",
    "sandbox": false,
    "chatId": "1613387504.052.02589455-7427-4036-8573-a8eb55f69520",
    "value": {
        "name": "button",
        "value": "Button value"
    }
}
```

### Make transition

If you have a triggered scenario that contains buttons with a transition to another scenario you have to send the request with type scenario. You either link to the top of the scenario by passing the scenario id or link to a state in that scenario by adding the state id.&#x20;

```javascript
{
    "type": "scenario",
    "sandbox": false,
    "chatId": "1613387504.052.02589455-7427-4036-8573-a8eb55f69520",
    "value": {
        "scenario": "82cd1000-6f61-11eb-aed8-d37ca2e276ae_f3e9282a-5502-4dc2-bffc-b1b9efa7aa3a"
    }
}
```

## Outgoing webhooks

Outgoing webhooks allows you to subscribe to certain events in the conversation. This is useful if you would like to add triggers on your side based on things happening in the conversation. It's also useful if you would like to keep track of conversations in real time.&#x20;

Head to the webhook page in the integration section on the left sided menu and click on add and then click on outgoing as a type. Once you have done so you have to select the topics that you would like to subscribe to.&#x20;

### Overview

| Topic                                       | Description                                               |
| ------------------------------------------- | --------------------------------------------------------- |
| [chat.create](#chat.create)                 | when the chat is created                                  |
| [chat.update](#chat.update)                 | when the chat is updated                                  |
| [chat.data.update](#chat.data.update)       | when the conversations property in the session is updated |
| [chat.user.update](#chat.user.update)       | when the chat user entity is updated                      |
| [chat.user.message](#chat.user.message)     | subset of chat.message holds just the user’s messages     |
| [chat.bot.message](#chat.bot.message)       | subset of chat.message holds just the bot’s messages      |
| [chat.agent.message](#chat.agent.message)   | subset of chat.message holds just the agent’s messages    |
| [chat.system.message](#chat.system.message) | subset of chat.message holds just the system’s messages   |
| [chat.message](#chat.message)               | handles all messages sent in the chat                     |
| [chat.scenario.run](#chat.scenario.run)     | when a scenario is executed                               |
| [chat.status.change](#chat.)                | subset of chat.update holds just the status update        |
| [chat.close](#chat.close)                   | when the chat is closed, sends the whole chat transcript  |

### Details

#### chat.create

Example:

```json
{
    "topic": "chat.create",
    "botId": "<BOT_ID>",
    "data": {
      "id": "<CHAT_ID>",
      "type": "web",
      "status": "ongoing",
      "user": { "first_name": "Identical", "last_name": "Goat" }
    },
    "context": {
      "company_id": "",
      "user_id": "",
      "impersonated_user_id": "",
      "request_id": "<REQUEST_ID>"
    },
    "requestId": "<REQUEST_ID>",
    "timestamp": 1672531200000
  }
```

#### chat.update

Example:

```json
{
    "topic": "chat.update",
    "botId": "<BOT_ID>",
    "chat": {
      "id": "<CHAT_ID>",
      "botId": "<BOT_ID>",
      "companyId": "<COMPANY_ID>",
      "name": "Name Goat",
      "integration_type": "web",
      "scenario": null,
      "type": "close_chat",
      "status": "ongoing",
      "statusTimestamp": "1672531200.427187915",
      "chatUserId": "<CHAT_USER_ID>",
      "handled_by": "bot",
      "handledByAgentTimestamp": null,
      "transfer_data": {},
      "userId": null,
      "last_message": "1672531200.085565643",
      "new_messages": false,
      "scenarios_in_progress": [],
      "successful_scenarios": {},
      "language": "sv",
      "nps": null,
      "rating": null,
      "transferSkillId": null,
      "participants": [],
      "agents": [],
      "createdAt": "2023-01-01T07:34:43.000Z",
      "updatedAt": "2023-01-01T07:36:11+00:00",
      "chat_user": {
        "id": "<CHAT_USER_ID>",
        "image": null,
        "info": "{\"first_name\":\"Identical\",\"last_name\":\"Goat\"}",
        "createdAt": "2023-01-01T07:34:43.000Z",
        "updatedAt": "2023-01-01T07:34:43.000Z"
      },
      "supervised": false
    },
    "context": {
      "company_id": "",
      "user_id": "",
      "impersonated_user_id": "",
      "request_id": "<REQUEST_ID>"
    },
    "requestId": "<REQUEST_ID>",
    "timestamp": 1672531200000
  }
```

#### chat.data.update

Example:

```json
{
  "topic": "chat.data.update",
  "botId": "<BOT_ID>",
  "data": {
    "id": "<CHAT_ID>",
    "time_before_start": 0,
    "os": "Windows",
    "user_last_input": "test",
    "current_host": "<WEBSITE_HOST>",
    "clientIp": "<IP_ADRESS>",
    "browser": "chrome",
    "chat_theme_details": {
      "id": "<CHAT_THEME_ID>",
      "path": null,
      "isDefault": true
    },
    "current_page": "<WEBSITE_PAGE>",
    "platform": "web"
  },
  "context": {
    "company_id": "",
    "user_id": "",
    "impersonated_user_id": "",
    "request_id": "<REQUEST_ID>"
  },
  "requestId": "<REQUEST_ID>",
  "timestamp": 1672531200000
}
```

#### chat.user.update

Example:

```json
{
  "topic": "chat.user.update",
  "botId": "<BOT_ID>",
  "data": {
    "id": "<CHAT_ID>",
    "user": { "first_name": "Name", "id": "<CHAT_USER_ID>" }
  },
  "context": {
    "company_id": "",
    "user_id": "",
    "impersonated_user_id": "",
    "request_id": "<REQUEST_ID>"
  },
  "requestId": "<REQUEST_ID>",
  "timestamp": 1672531200000
},
```

#### chat.user.message

Example:

```json
{
  "topic": "chat.user.message",
  "botId": "<BOT_ID>",
  "data": {
    "chatId": "<CHAT_ID>",
    "sender": "user",
    "value": "<MESSAGE>",
    "type": "text",
    "id": "<USER_ID>",
    "timestamp": "1672531200000.397183857"
  },
  "context": {
    "company_id": "",
    "user_id": "",
    "impersonated_user_id": "",
    "request_id": "<REQUEST_ID>"
  },
  "requestId": "<REQUEST_ID>",
  "timestamp": 1672531200000
}
```

#### chat.bot.message

Example:

```json
{
  "topic": "chat.bot.message",
  "botId": "<BOT_ID>",
  "data": {
    "chatId": "<CHAT_ID>",
    "sender": "bot",
    "value": {
      "description": "Didn't quite get that... Would you like human help instead?",
      "urls": [
        {
          "id": "ef7af21c-d875-41f2-9d36-6bfe191cd58c",
          "label": "Yes",
          "type": "scenario",
          "next": {
            "scenario": "<SCENARIO_ID>",
            "state": "fba34726-bd31-4ef2-964a-3cf9a64f5df5"
          }
        },
        {
          "id": "cb029428-6513-4540-b3e2-44ed9e832bdc",
          "label": "No",
          "type": "scenario"
        }
      ]
    },
    "type": "url",
    "id": "f7011d1a-e192-4351-9251-c0c6d3b32524",
    "timestamp": "1672531200000.241731866"
  },
  "context": {
    "company_id": "",
    "user_id": "",
    "impersonated_user_id": "",
    "request_id": "<REQUEST_ID>"
  },
  "requestId": "<REQUEST_ID>",
  "timestamp": 1672531200000
}
```

#### chat.agent.message

Example:

```json
{
  "topic": "chat.agent.message",
  "botId": "<BOT_ID>",
  "data": {
    "chatId": "<CHAT_ID>",
    "sender": "agent",
    "value": "<MESSAGE>",
    "type": "text",
    "id": "e8328e60-6757-48ea-87d1-3be485348b4c",
    "timestamp": "1672531200.310412954"
  },
  "context": {
    "company_id": "",
    "user_id": "",
    "impersonated_user_id": "",
    "request_id": "<REQUEST_ID>"
  },
  "requestId": "<REQUEST_ID>",
  "timestamp": 1672531200000
}
```

#### chat.system.message

Example:

```json
{
  "topic": "chat.system.message",
  "botId": "<BOT_ID>",
  "data": {
    "chatId": "<CHAT_ID>",
    "sender": "system",
    "value": "<MESSAGE>",
    "type": "text_info",
    "id": "2276d442-3af1-4f80-a21b-c405632e3b60",
    "timestamp": "1672531200000.158836861"
  },
  "context": {
    "company_id": "",
    "user_id": "",
    "impersonated_user_id": "",
    "request_id": "<REQUEST_ID>"
  },
  "requestId": "<REQUEST_ID>",
  "timestamp": 1672531200000
}
```

#### chat.message

*Any of the chat.\<sender>.message.*

#### chat.scenario.run

Example:

```json
{
  "topic": "chat.scenario.run",
  "botId": "<BOT_ID>",
  "data": {
    "chatId": "<CHAT_ID>",
    "scenario": {
      "id": "<SCENARIO_ID>",
      "name": "<SCENARIO_NAME>",
      "states": 1
    }
  },
  "context": {
    "company_id": "",
    "user_id": "",
    "impersonated_user_id": "",
    "request_id": "<REQUEST_ID>"
  },
  "requestId": "<REQUEST_ID>",
  "timestamp": 1672531200000
}
```

#### chat.status.change

Example:

```json
{
  "topic": "chat.status.change",
  "botId": "<BOT_ID>",
  "data": {
    "id": "<CHAT_ID>",
    "status": "ongoing",
    "supervised": false,
    "type": "scenario"
  },
  "context": {
    "company_id": "",
    "user_id": "",
    "impersonated_user_id": "",
    "request_id": "<REQUEST_ID>"
  },
  "requestId": "<REQUEST_ID>",
  "timestamp": 1672531200000
}
```

#### chat.close

Example:

```json
{
  "topic": "chat.close",
  "botId": "<BOT_ID>",
  "data": {
    "id": "<CHAT_ID>",
    "conversation": [
      {
        "id": "<MESSAGE_ID>",
        "sender": "user",
        "type": "scenario",
        "value": {
          "scenario": "<SCENARIO_ID>"
        },
        "timestamp": "1672531200.063057626"
      },
      {
        "id": "<MESSAGE_ID>",
        "sender": "bot",
        "type": "rating_request",
        "value": { "question": "<MESSAGE>" },
        "timestamp": "1672531200.718404236"
      },
      {
        "id": "<MESSAGE_ID>",
        "sender": "user",
        "type": "rating",
        "value": { "rating": 5 },
        "timestamp": "1672531200.575724287"
      },
      {
        "id": "<MESSAGE_ID>",
        "sender": "bot",
        "type": "url",
        "value": {
          "description": "<MESSAGE>",
          "urls": [
            {
              "id": "<BUTTON_ID>",
              "label": "<LABEL>",
              "type": "url",
              "value": "ebbot://reset"
            }
          ]
        },
        "timestamp": "1672531200.620270927"
      }
    ]
  },
  "context": {
    "company_id": "",
    "user_id": "",
    "impersonated_user_id": "",
    "request_id": "<REQUEST_ID>"
  },
  "requestId": "<REQUEST_ID>",
  "timestamp": 1672531200000
}
```


---

# 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://docs.ebbot.ai/ebbot-docs/developer-resources/ebbot-chat/webhooks.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.