Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

improving docs #791

Merged
merged 2 commits into from
Jul 9, 2024
Merged

improving docs #791

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1a92443
improving docs
codebanesr Jul 9, 2024
b1063a8
Fixing docs
codebanesr Jul 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 91 additions & 38 deletions docs/api-reference/endpoint/conversation-history.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,107 @@
---
title: "Chat Conversations"
api: "GET https://api-v2.opencopilot.so/backend/chat/:organization_id"
description: "Retrieve paginated chat conversations, including if the conversatin was a handoff and the sentiment with the summary."
title: "Get Chat Conversations"
api: "GET https://api-v2.opencopilot.so/backend/chat/{organization_id}"
description: "Retrieve paginated chat conversations, including handoff status and sentiment summary."
---

<Warning>
This endpoint is protected by the same JWT that the user uses to call other APIs. The response will include data for the specified chatbot, along with other metadata information.
</Warning>
This endpoint allows you to retrieve all conversations for a specific Organization ID. The response includes the conversation id, sentiment, and reason for handoff (if applicable).

## Authentication

<Warning>
This endpoint points to the (v2) version of the API. The (v2) version of the API is the latest version and is recommended for all new development. Please update your code to use the (v2) version of the API.
</Warning>
<ParamField header="Authorization" type="string" required>
Bearer token for authentication
</ParamField>

This endpoint allows you to retrieve all conversations for a specific Organization ID. The response includes the conversation id, sentiment, and reason for handoff (if applicable).
## Path Parameters

<ParamField path="organization_id" type="string" required>
The unique identifier of the organization
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default="1">
The page number to retrieve
</ParamField>

<ParamField query="limit" type="integer" default="10">
The number of items to retrieve per page
</ParamField>

<ParamField query="sortBy" type="string" default="created_at">
The field to sort by
</ParamField>

<ParamField query="sortDirection" type="string" default="ASC">
The direction to sort (ASC or DESC)
</ParamField>

## Response

<ResponseField name="id" type="string">
The unique identifier for the chat conversation
</ResponseField>

<ResponseField name="copilot_id" type="string">
The unique identifier for the organization (copilot) associated with the conversation
</ResponseField>

<ResponseField name="created_at" type="string">
The date and time the conversation was created
</ResponseField>

The endpoint is paginated, and you can specify the `page` and `limit` query parameters to control the amount of data returned.
<ResponseField name="channel" type="string">
The channel on which the conversation was created (whatsapp, email, web, or phone)
</ResponseField>

<ResponseField name="summary" type="string">
A summary of the conversation (only available for conversations marked as handoff)
</ResponseField>

<ResponseField name="classification" type="string">
The classification of the conversation (based on the user's provided categories and tags)
</ResponseField>

<ResponseField name="assignee_id" type="string">
The ID of the assignee for the conversation
</ResponseField>

<ResponseField name="handoff" type="boolean">
Indicates whether the conversation was handed off to a human agent
</ResponseField>

<ResponseField name="handoff_sentiment" type="string">
The sentiment of the conversation at the time of handoff
</ResponseField>

<ResponseField name="status" type="string">
The status of the conversation (open, resolved, or closed)
</ResponseField>

<ResponseField name="meta" type="object">
Metadata about the conversation (such as title, recording URL, and phone number)
</ResponseField>

<ResponseField name="action_called" type="integer">
The number of actions called during the conversation
</ResponseField>

<ResponseField name="total_messages" type="integer">
The total number of messages in the conversation
</ResponseField>

<RequestExample>

```bash Example Request
curl --location 'https://api-v2.opencopilot.so/backend/chat/:organization_id' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json'
curl --location 'https://api-v2.opencopilot.so/backend/chat/your-organization-id' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json'
```

</RequestExample>

<ResponseExample>

```json Response
[
{
Expand All @@ -45,28 +121,5 @@ curl --location 'https://api-v2.opencopilot.so/backend/chat/:organization_id' \
}
]
```
</ResponseExample>

**The request includes the following optional query parameters:**
- `page`: The page number to retrieve (default is 1).
- `limit`: The number of items to retrieve per page (default is 10).
- `sortBy`: The field to sort by (default is `created_at`).
- `sortDirection`: The direction to sort (default is `ASC`) (`ASC` or `DESC`).

----

**The response includes the following fields:**

- `id`: The unique identifier for the chat conversation.
- `copilot_id`: The unique identifier for the organization (copilot) associated with the conversation.
- `created_at`: The date and time the conversation was created.
- `channel`: The channel on which the conversation was created (`whatsapp`, `email`, `web`, or `phone`).
- `summary`: A summary of the conversation (only avaliable for conversations that is marked as `handoff`).
- `classification`: The classification of the conversation (based on the user's provided categories and tags).
- `assignee_id`: The ID of the assignee for the conversation (will be `copilot` for conversations that are not assigned to a human, otherwise will be the ID of the assignee).
- `handoff_sentiment`: The sentiment of the conversation at the time of handoff.
- `handoff_summary`: A summary of the conversation at the time of handoff.
- `handoff`: A boolean value indicating whether the conversation was handed off to a human agent.
- `status`: The status of the conversation (open, resolved, or closed).
- `meta`: Metadata about the conversation (such as title, recording URL, and phone number).

</ResponseExample>
101 changes: 63 additions & 38 deletions docs/api-reference/endpoint/conversation-messages.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,89 @@
---
title: "Messages"
api: "GET https://api-v2.opencopilot.so/backend/conversations/:bot_id/messages/:conversation_id"
title: "Get Messages"
api: "GET https://api-v2.opencopilot.so/backend/chat/sessions/{sessionId}/chats"
description: "Retrieve all messages for a specific conversation."
---

<Warning>
This endpoint is protected by the same JWT that the user uses to call other APIs. The response will include data for the specified chatbot, along with other metadata information.
</Warning>
This endpoint retrieves all messages for a specific conversation. You can use the `conversation_id` parameter to specify the conversation for which you want to retrieve messages. To get the `conversation_id`, use the get conversations endpoint.

<Warning>
This endpoint points to the (v2) version of the API. The (v2) version of the API is the latest version and is recommended for all new development. Please update your code to use the (v2) version of the API.
</Warning>
The endpoint is paginated, and you can specify the `offset` and `limit` parameters to control the amount of data returned.

### Path Parameters

This endpoint retrieves all messages for a specific conversation. You can use the `conversation_id` parameter to specify the conversation for which you want to retrieve messages, to the conversation_id parameter, use get conversations endpoint to get the conversation_id.
<ParamField path="sessionId" type="string" required>
The ID of the conversation for which to retrieve messages.
</ParamField>

The endpoint is paginated, and you can specify the `offset` and `limit` parameters to control the amount of data returned.
### Query Parameters

<ParamField query="offset" type="integer" default="0">
The number of items to skip before starting to collect the result set.
</ParamField>

<ParamField query="limit" type="integer" default="50">
The maximum number of items to return.
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
Bearer token for authentication.
</ParamField>

<RequestExample>
```bash Example Request
curl --location 'https://api-v2.opencopilot.so/backend/conversations/:bot_id' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json'
curl --location 'https://api-v2.opencopilot.so/backend/conversations/{bot_id}/messages/{conversation_id}?offset=0&limit=10' \
--header 'Authorization: Bearer YOUR_TOKEN'
```
</RequestExample>

<ResponseExample>
```json Response
[
{
"action_called": false,
"client_extra_params": {},
"from": "copilot",
"knowldgebase_called": false,
"message": "Hello! How can I assist you today?"
},
{
"action_called": false,
"client_extra_params": {},
"from": "user",
"knowldgebase_called": false,
"message": "hey"
}
{
"action_called": false,
"client_extra_params": {},
"from": "copilot",
"knowldgebase_called": false,
"message": "Hello! How can I assist you today?"
},
{
"action_called": false,
"client_extra_params": {},
"from": "user",
"knowldgebase_called": false,
"message": "hey"
}
]
```
</ResponseExample>

The response includes the following fields:
### Response Fields

- `action_called`: A boolean value that indicates whether the action was called to handle the message.
- `client_extra_params`: An object that contains additional parameters that the client can send to the bot.
- `from`: A string that indicates the sender of the message. The value can be `copilot` or `user`.
- `knowldgebase_called`: A boolean value that indicates whether the knowledge base was called to handle the message.
- `message`: A string that contains the message text.
<ResponseField name="action_called" type="boolean">
Indicates whether an action was called to handle the message.
</ResponseField>

<ResponseField name="client_extra_params" type="object">
Additional parameters that the client can send to the bot.
</ResponseField>

<ResponseField name="from" type="string">
The sender of the message. Can be 'copilot' or 'user'.
</ResponseField>

You can use the `offset` and `limit` parameters to control the pagination of the response. For example, to retrieve the first 10 messages, you can use the following request:
<ResponseField name="knowldgebase_called" type="boolean">
Indicates whether the knowledge base was called to handle the message.
</ResponseField>

```bash Example Request
curl --location 'https://api-v2.opencopilot.so/backend/conversations/:bot_id/messages/:conversation_id?offset=0&limit=10' \
--header 'Authorization: Bearer TOKEN'
```
<ResponseField name="message" type="string">
The message text.
</ResponseField>

<Warning>
This endpoint is protected by the same JWT that the user uses to call other APIs. The response will include data for the specified chatbot, along with other metadata information.
</Warning>

<Warning>
This endpoint points to the (v2) version of the API. The (v2) version of the API is the latest version and is recommended for all new development. Please update your code to use the (v2) version of the API.
</Warning>
Loading