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

200

{"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.

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

200

ok

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

200

{"type" => "result, "message" => "Attachment uploaded.", "ticketID" => X, "messageID" => X}

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

200

ok

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

200

{"type" => "result, "message" => "Event sent."}

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

200

ok

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)

200

{"type": "result", "message": "Session ended."}

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

200

{
  "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": "[e-mail]",
    "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": []
    }
  ]
}

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

200

{
  "result": "success",
  "message": "Chatbot ticket created."
}

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

200

{ "message": "ok" }