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):

post
New chat message from the customer to the agent

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.
Request
Response
Request
Path Parameters
messageNumber
optional
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
required
string
the url the chat was created from, for instance: https://www.brand.com/support
message
required
string
customer message or chatbot history
channelID
required
integer
use "8" for live chat
chatAccountToken
required
string
A token to be created in omnidesk
chatSessionID
required
string
Your session id
chatServer
required
string
Your server IP / hostname: hookpoint base
Response
200: OK
{"type": "result", "message": "Message sent.", "ticketID": 12312}

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.

post
New message from the agent to the customer (hookpoint)

{{ chatServer }}/messageForCustomer
This hookpoint will receive responses from the agent to the customer
Request
Response
Request
Path Parameters
picture
optional
string
Picture of the agent if uploaded
name
required
string
Name of the replying agent
message
required
string
Message of the agent
sessionID
required
string
Your session ID
Response
200: OK
ok

post
File upload from the customer to the agent

https://account.omnidesk.com/api/v2/addAttachment
Use this endpoint to upload an attachment from the customer to the agent.
Request
Response
Request
Body Parameters
file
optional
object
binary of the actual file
chatServer
required
string
chatAccountToken
required
string
Response
200: OK
{"type" => "result, "message" => "Attachment uploaded.", "ticketID" => X, "messageID" => X}

post
File upload from the agent to the customer (hookpoint)

{{ chatserver }}/uploadForCustomer
This hookpoint will receive attachments from the agent to the customer.
Request
Response
Request
Path Parameters
file
required
object
the actual binary file
sessionID
required
string
Id of the session
Response
200: OK
ok

post
Typing indicator and other events for the customer

https://account.omnidesk.com/api/v2/chat/notifyUserNewChatEvent
Request
Response
Request
Body Parameters
chatServer
required
string
chatSessionID
required
string
event
required
string
startedtyping|stoppedtyping|expandedchat|minimizedchat
Response
200: OK
{"type" => "result, "message" => "Event sent."}

post
Typing indicator for customer (hookpoint)

{{ chatserver}}/typingIndicatorForCustomer
This hookpoint will receive an indication when the agent is typing or not.
Request
Response
Request
Path Parameters
Typing
required
boolean
Sets the typing indicator
SessionID
required
string
Session id of the chat
Response
200: OK
ok

post
End the session (timeout or other trigger)

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.
Request
Response
Request
Path Parameters
chatSessionID
required
string
Your session ID
chatServer
required
string
Your server IP / hostname (REQUIRED)
Response
200: OK
{"type": "result", "message": "Session ended."}

get
Request if agents available with the si

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).
Request
Response
Request
Path Parameters
chatAccountToken
required
string
your chataccount token
chatServerToken
required
string
your chatserver token
Response
200: OK
{
"type": "result",
"message": "start instructions",
"config": {
"chat_logo": "https://www.omnidesk.nl/img/logo_white.svg",
"header_color": "#18e2ae",
"chat_logo_height": "30",
"chat_logo_width": "100",
"chat_background_color": "#e5e5e5",
"chat_message_customer_color": "#ffffff",
"chat_message_customer_text_color": "#000000",
"chat_message_agent_color": "#18e2ae",
"chat_message_agent_text_color": "#000000",
"chat_textarea_placeholder": "Type je vraag en druk op enter",
"chat_introduction_html": "",
"label_provide_email_address": "Please provide your mail address",
"label_provide_phone_number": "Please provide your phone number",
"placeholder_email_address": "[email protected]",
"placeholder_telephone_number": "0612345678",
"start_button_color": "#232541",
"start_chat_instructions": "Welkom! Typ je vraag, iemand van onze klantenservice komt zo bij je.",
"session_timeout_warning": "notice: due to inactivity this session will soon close",
"session_timeout_message": "session closed, refresh window to start a new chat",
"file_uploaded_text": "File uploaded.",
"agent_typing_text": "Agent typing..",
"show_survey_after_chat": null
},
"instructions": [
{
"type": "hide_reason_no_agents_available"
},
{
"type": "phoneNumber",
"key": "phoneNumber"
},
{
"type": "show_team",
"team_profile_pictures": []
}
]
}

post
Create chatbot log

https://account.omnidesk.com/api/v2/message/chatbot
This endpoint can be used to push the chatbot history to Omnidesk.
Request
Response
Request
Form Data Parameters
from
required
string
from address of the customer (email or phone number)
subject
required
string
subject of the ticket
message
required
string
the actual conversation history, markdown compatible
brandID
required
string
ID of the brand, see settings > brands
Response
200: OK
{
"result": "success",
"message": "Chatbot ticket created."
}

post
Push end session

{{ chatserver}}/endSession
Stops the chat as of the agent clicked on the stop button in the ticket interface
Request
Response
Request
Path Parameters
sessionID
required
string
Your session ID
Response
200: OK
{
"message": "ok"
}