diff --git a/docs/channels/api-channel/callback-url.md b/docs/channels/api-channel/callback-url.md new file mode 100644 index 000000000..09373e09f --- /dev/null +++ b/docs/channels/api-channel/callback-url.md @@ -0,0 +1,45 @@ +--- +path: '/docs/channels/api/callback-url' +title: 'Callback URL and message payload' +--- + +When a new message is created in the API channel, you will get a POST request to the Callback URL specified while creating the API channel. The payload would look like this. + +**Event type**: `message_created` + +```json +{ + "id": 0, + "content": "This is a incoming message from API Channel", + "created_at": "2020-08-30T15:43:04.000Z", + "message_type": "incoming", + "content_type": null, + "content_attributes": {}, + "source_id": null, + "sender": { + "id": 0, + "name": "contact-name", + "avatar": "", + "type": "contact" + }, + "inbox": { + "id": 0, + "name": "API Channel" + }, + "conversation": { + "additional_attributes": null, + "channel": "Channel::Api", + "id": 0, + "inbox_id": 0, + "status": "open", + "agent_last_seen_at": 0, + "user_last_seen_at": 0, + "timestamp": 0 + }, + "account": { + "id": 1, + "name": "API testing" + }, + "event": "message_created" +} +``` diff --git a/docs/channels/api-channel/create-channel.md b/docs/channels/api-channel/create-channel.md new file mode 100644 index 000000000..0b7d2ce14 --- /dev/null +++ b/docs/channels/api-channel/create-channel.md @@ -0,0 +1,34 @@ +--- +path: '/docs/channels/api/configure' +title: 'How to create an API channel inbox?' +--- + +Setting up an API channel consists of the following steps. + +1. Create API Channel inbox +2. Send messages using Chatwoot APIs +3. Receive webhooks on new messages from Chatwoot + +This document allows you to create and configure an API channel inbox in Chatwoot installations. + +**Step 1**: Go to Settings > Inboxes and click on "Add Inbox". + +**Step 2**: Select **API** from the list of channels. + +![select-api-inbox](./images/select-api-inbox.png) + +**Step 3**: Provide an name for the channel and a callback URL (the events and corresponding payload is defined in the subsequent articles) + +![configure-screen](./images/configure-screen.png) + +**Step 4**: Add agents to the inbox. + +![add-agents](./images/add-agents.png) + +**Step 5**: Hooray!! The inbox setup is complete. + +![take-me-there](./images/take-me-there.png) + +![inbox-welcome-screen](./images/inbox-welcome-screen.png) + +Now the channel setup is complete, let us try to send a message using Chatwoot APIs. Read more about it [here](/docs/channels/api/send-messages) diff --git a/docs/channels/api-channel/images/add-agents.png b/docs/channels/api-channel/images/add-agents.png new file mode 100644 index 000000000..6a67ddf79 Binary files /dev/null and b/docs/channels/api-channel/images/add-agents.png differ diff --git a/docs/channels/api-channel/images/configure-screen.png b/docs/channels/api-channel/images/configure-screen.png new file mode 100644 index 000000000..00dd8c336 Binary files /dev/null and b/docs/channels/api-channel/images/configure-screen.png differ diff --git a/docs/channels/api-channel/images/conversation.png b/docs/channels/api-channel/images/conversation.png new file mode 100644 index 000000000..94be3952d Binary files /dev/null and b/docs/channels/api-channel/images/conversation.png differ diff --git a/docs/channels/api-channel/images/inbox-welcome-screen.png b/docs/channels/api-channel/images/inbox-welcome-screen.png new file mode 100644 index 000000000..7e3af959e Binary files /dev/null and b/docs/channels/api-channel/images/inbox-welcome-screen.png differ diff --git a/docs/channels/api-channel/images/select-api-inbox.png b/docs/channels/api-channel/images/select-api-inbox.png new file mode 100644 index 000000000..770b6135e Binary files /dev/null and b/docs/channels/api-channel/images/select-api-inbox.png differ diff --git a/docs/channels/api-channel/images/take-me-there.png b/docs/channels/api-channel/images/take-me-there.png new file mode 100644 index 000000000..8add8e622 Binary files /dev/null and b/docs/channels/api-channel/images/take-me-there.png differ diff --git a/docs/channels/api-channel/send-message-api-channel.md b/docs/channels/api-channel/send-message-api-channel.md new file mode 100644 index 000000000..9a82700ef --- /dev/null +++ b/docs/channels/api-channel/send-message-api-channel.md @@ -0,0 +1,113 @@ +--- +path: '/docs/channels/api/send-messages' +title: 'Send messages to API channel' +--- + +To send messages to API channel, you need have a basic understanding of the models and nomenclature used in Chatwoot. Let us try to understand these first. + +1. **Channel**: Channel defines the type of the source of conversations. Eg: Facebook, Twitter, API etc. + +2. **Inbox**: You can create multiple sources of conversations which is of the same channel type. For eg: You can have more than one Facebook page connected to a Chatwoot account. Each page is called as the inbox in Chatwoot. + +3. **Conversation**: A Conversation is a collection of messages. + +4. **Contact**: Each conversation has a real life person associated with it, this person is called a contact. + +5. **Contact Inboxes**: This is the session for each contact on a inbox. A contact can have multiple sessions and multiple conversations in the same inbox. + +### How to send a message in an API Channel? + +To send a message in an API channel, you have to create a contact, then create a conversation and then send a message. + +APIs require `api_access_token` in the request header. You can get this token by visiting your Profile settings > Access Token + +#### 1. Create a contact + +API documentation: (https://www.chatwoot.com/developers/api/#operation/contactCreate) + +Pass the inbox id of the API channel along with other params specified. This would create a session for you automatically. A sample response would look like the one below. + +```json +{ + "email": "string", + "name": "string", + "phone_number": "string", + "thumbnail": "string", + "additional_attributes": {}, + "contact_inboxes": [ + { + "source_id": "string", + "inbox": { + "id": 0, + "name": "string", + "website_url": "string", + "channel_type": "string", + "avatar_url": "string", + "widget_color": "string", + "website_token": "string", + "enable_auto_assignment": true, + "web_widget_script": "string", + "welcome_title": "string", + "welcome_tagline": "string", + "greeting_enabled": true, + "greeting_message": "string" + } + } + ], + "id": 0, + "availability_status": "string" +} +``` + +As you can see in the payload, you will be able to see the `contact_inboxes` and each `contact_inbox` will have a `source_id`. Source Id can be seen as the session identifier. You will use this source_id to create a new conversation as defined below. + +#### 2. Create a conversation + +API documentation: (https://www.chatwoot.com/developers/api/#operation/newConversation) + +Use the `source_id` received in the previous API call. + +You will receive a conversation id which can be used to create a message. + +```json +{ + "id": 0 +} +``` + +#### 3. Create a new message + +API documentation: (https://www.chatwoot.com/developers/api/#operation/conversationNewMessage) + +There are 2 types of messages. + +1. **Incoming**: Messages sent by the end user is classified as an incoming message. + +2. **Outgoing**: Messages sent by the agent is classified as an outgoing message. + +If you call the API with the correct content, you will receive a payload similar to the one below. + +```json +{ + "id": 0, + "content": "This is a incoming message from API Channel", + "inbox_id": 0, + "conversation_id": 0, + "message_type": 0, + "content_type": null, + "content_attributes": {}, + "created_at": 0, + "private": false, + "sender": { + "id": 0, + "name": "Pranav", + "type": "contact" + } +} +``` + +If everything is sucessful you will see the conversation on the dashboard as follows. + +![conversation](./images/conversation.png) + +You will be notified when a new message is created on the URL specified while creating the API channel. You can read about the message payload [here](/docs/channels/api/callback-url)