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.
Webhooks
You'll need to subscribe to the following events:
- chat-assigned
- chat-opened
- message-created
- chat-closed
- chat-reopened
- chat-rated
Admin API
You'll need to use the following mutations:
Setting up
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 (public@api.guuru.com) is part of your comunity.
Handling Personas
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
call 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.
The 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
same 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
calling createPersona with providerId set to the agent unique id and use
the returned id in the subsequent call to acceptChat.
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 api).
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
the sendChatMessage mutation.
message-created is triggered whenever a new message is created. Through
the 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 openChat mutation.
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.
Troubleshooting
If you need help or you are experiencing some problems setting up the protocol, please get in touch with our support.