GUURU for Developers

GUURU for Developers

  • Docs
  • Contacts

›Integrations

Loader

  • Getting Started
  • Public Interface
  • Handling Events
  • Conversion
  • Cookies
  • Examples

SmartChat

  • Getting started
  • Chat Widget

    • Getting started
    • Parameters

SmartForm

  • Getting Started

Admin API

  • Getting started
  • Examples
  • API Reference

    • Queries
    • Mutations
    • Types
    • Pagination

Webhooks

  • Getting started
  • Examples

Integrations

  • Facebook
  • Freshchat
  • Salesforce
  • Zendesk
  • Microsoft
  • Third Party Messaging

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:

  • createPersona
  • acceptChat
  • sendChatMessage
  • closeChat
  • openChat

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.

← Microsoft
  • Webhooks
  • Admin API
  • Setting up
    • Public API service account
    • Handling Personas
    • Handle the webhook events
    • Interact with the Admin API mutations
  • Troubleshooting
GUURU for Developers
Docs
SmartChatSmartFormAPI Reference
Community
GitLabFacebookLinkedIn
Copyright © 2023 GUURU Solutions Ltd.