Livechat chatbot and app integration (backend)
The omnidesk chat service is well suited to be integrated with your own app or chatbot. You can use our API to push the chatbot history and provide a way to escalate. These docs can also be used to integrate our chat with your mobile apps (android/iphone).
Session management
Because you are building an app or chatbot you probably already have a unique session ID of your current session. Our service requires that you provide a unique chat session id. You are in control of the session.
Escalate a chat from chatbot to a live person
You can use our API call notifyUserNewChatMessage to create a new chat session and you can also use this same endpoint to post new messages. This is supposed to be used at your backend / middleware.
Example of a new escalation (and creation of a ticket consequently):
New chat message from the customer to the agent
POST
https://account.omnidesk.com/api/v2/chat/notifyUserNewChatMessage
This endpoint can be used to send new messages from the customer to the agent. For the first message it will create a new session. Be sure to provide a unique chatSessionID that will remain the same for the entire session.
Path Parameters
Name | Type | Description |
---|---|---|
messageNumber | integer | The message count within this chat session, starting with 1 for the first message you send in the session. Recommended to use, not required. |
url | string | the url the chat was created from, for instance: https://www.brand.com/support |
message | string | customer message or chatbot history |
channelID | integer | use "8" for live chat |
chatAccountToken | string | A token to be created in omnidesk |
chatSessionID | string | Your session id |
chatServer | string | Your server IP / hostname: hookpoint base |
All consequent messages should also be posted to this endpoint. Provide the same sessionID so that it will go to the same ticket and support agent, if not it will create a new ticket.
Handle agent response
The response of the chat agent will be posted to the chatServer hookpoint. The response will be posted to {{ chatServer }}/ messageForCustomer, see below.
New message from the agent to the customer (hookpoint)
POST
{{ chatServer }}/messageForCustomer
This hookpoint will receive responses from the agent to the customer
Path Parameters
Name | Type | Description |
---|---|---|
picture | string | Picture of the agent if uploaded |
name | string | Name of the replying agent |
message | string | Message of the agent |
sessionID | string | Your session ID |
File upload from the customer to the agent
POST
https://account.omnidesk.com/api/v2/chat/addAttachment
Use this endpoint to upload an attachment from the customer to the agent.
Request Body
Name | Type | Description |
---|---|---|
file | object | binary of the actual file |
chatServer | string | |
chatAccountToken | string | |
sessionID | string |
File upload from the agent to the customer (hookpoint)
POST
{{ chatserver }}/uploadForCustomer
This hookpoint will receive attachments from the agent to the customer.
Path Parameters
Name | Type | Description |
---|---|---|
file | object | the actual binary file |
sessionID | string | Id of the session |
Typing indicator and other events for the customer
POST
https://account.omnidesk.com/api/v2/chat/notifyUserNewChatEvent
Request Body
Name | Type | Description |
---|---|---|
chatServer | string | |
chatSessionID | string | |
event | string | startedtyping|stoppedtyping|expandedchat|minimizedchat |
Typing indicator for customer (hookpoint)
POST
{{ chatserver}}/typingIndicatorForCustomer
This hookpoint will receive an indication when the agent is typing or not.
Path Parameters
Name | Type | Description |
---|---|---|
Typing | boolean | Sets the typing indicator |
SessionID | string | Session id of the chat |
End the session (timeout or other trigger)
POST
https://account.omnidesk.com/api/v2/message/notifyUserEndChat
As mentioned above your software is in control of the session. With this endpoint you can let Omnidesk know the session ended.
Path Parameters
Name | Type | Description |
---|---|---|
chatSessionID | string | Your session ID |
chatServer | string | Your server IP / hostname (REQUIRED) |
Request if agents available with the si
GET
https://chat.omnidesk.io/requestChatConfig
First make sure the option "Hide chat when there are no agents available" is checked at your chat token configuration (Settings > Channels > Live chat > Tokens) and click the update-button. When there are no agents available there will be an instruction in the response of requestChatConfig that contains: "type": "hide_reason_no_agents_available". See a full example of such a response at the Response tab below (look for the key "instructions"). When there are agents available this instruction will not be in the response (there is not a instruction that states that there ARE agents available).
Path Parameters
Name | Type | Description |
---|---|---|
chatAccountToken | string | your chataccount token |
chatServerToken | string | your chatserver token |
Create chatbot log
POST
https://account.omnidesk.com/api/v2/message/chatbot
This endpoint can be used to push the chatbot history to Omnidesk.
Request Body
Name | Type | Description |
---|---|---|
from | string | from address of the customer (email or phone number) |
subject | string | subject of the ticket |
message | string | the actual conversation history, markdown compatible |
brandID | string | ID of the brand, see settings > brands |
Push end session
POST
{{ chatserver}}/endSession
Stops the chat as of the agent clicked on the stop button in the ticket interface
Path Parameters
Name | Type | Description |
---|---|---|
sessionID | string | Your session ID |
Last updated