Third Party Messaging
You may want to handle chat requests with agents on your own platform. Using GUURU as a frontface, it's possible to do it with the existing tools.
You'll be making use of our Webhooks and Admin API.
You'll need to subscribe to the following events:
You'll need to use the following mutations:
Public API service account
In order to interact with the admin api and make use of the mutations, you'll
need to make sure the agent
Public API service account (firstname.lastname@example.org) is part of your comunity.
To accept chats, you will use personas. They will represent the agents on your customer care service.
We will need to store some information of the personas in order to properly present those agents to the end user.
You Create Persona by calling the
mutation with the name of the agent and its unique id on your system, which we
providerId. Optionally, you can also set an email and photo.
The mutation will return an ID that can be used when accepting or transferring chats to personas. You can store this ID to map your agents to personas.
When an agent accepts a chat check if there is already an entry in the map
between agents and personas. If there is, call
acceptChat with the existing
persona id. If not, call
createPersona, store the id returned and call
acceptChat with it.
providerId will work in a similar way to a idempotency key. If multiple
calls to create persona are issued with the same
providerId the same persona
id is returned (no new personas are created). If a subsequent call passes the
providerId but a different value for a field (e.g. a different name) the
persona will be updated and the same id will be returned.
In environments where it is not possible to store the persona id returned by
createPersona you can use the behaviour above to your advantage by always
providerId set to the agent unique id and use
the returned id in the subsequent call to
Handle the webhook events
After setting up the webhooks, you'll have to understand what each event represents.
chat-assigned represents that a chat has been matched to a pool of experts
and is waiting to be accepted. A field
requestedExperts will be present, which
represents the pool of experts that can accept the chat. You'll be able to
accept the chat with
acceptChat mutation to start exchanging messages with the
end user. For the purpose of this type of integration, you should handle chats
that are requested to the
Public API service account (has the id
chat-opened occurs when a chat is accepted by an expert.
After this event, the chat cannot be accepted again (unless it's re-assgined for various reasons,
which will fire another chat-assigned).
The expert that accepted the chat can send messages to the end user with
message-created is triggered whenever a new message is created. Through
chat.id field you can map it to an existing chat.
chat-closed is an event stating that the chat is resolved. It's usually
preceded by the
closeChat mutation. Interactions between expert and end user
are not possible anymore.
chat-reopened can occur after a chat has been closed. It means the expert or
the end user decided the chat needed more interactions before being properly
resolved. Experts can reopen a chat with the
chat-rated is the final state of the chat. The end user has rated the expert performance. After being rated, the chat cannot be reopened or any message can be exchanged.
Interact with the Admin API mutations
After setting up the Admin API, you'll be able to interact directly with guuru. As stated before, you'll need to use a guuru persona id to use the necessary mutations to handle a chat conversation.
acceptChat is the mutation to use to start interacting with the end user. See the example to also get all the messages from the chat to that point.
sendChatMessage will be used to send messages to the chat. They can be simple text messages or links to attachments.
closeChat must be used to finish the interaction when the end user issue is resolved. Usually the user cannot close the chat, so the expert must close it on a reasonable way.
openChat can be used to reopen a chat if it was prematurely closed.
If you need help or you are experiencing some problems setting up the protocol, please get in touch with our support.