Introduction

Welcome to the Talkus Developer Documentation.

Talkus is very customizable and open. You’ll find on this page all the API and integration you can do with Talkus.

Definitions

Agent

An agent is an user of your company that is inside your Slack team and handle support requests.

Visitor

A visitor is one of your users that is not in Slack and contact you by a Talkus channel (email, live chat, sms, twitter…).

Visitor Channel

A Visitor Channel is a Slack channel where you interact with a specific visitor. It’s not the #talkus-support. Visitor Channel names always start with #z-.

API

Authorization

curl -X POST \
  --user '1234562a44147d1b3b3bad556784beae:' \
  https://app.talkus.io/api/test

When you call Talkus endpoints, you need to add the Authorization header using the Basic authentication type. The login will be the API Key you’ll find in the integration page and the password will be empty.

Send Message

Send a message from a new visitor (the visitorId will be created):

curl -X POST \
  --user '1234562a44147d1b3b3bad556784beae:' \
  -H 'Content-Type: application/json' \
  -d '{ "text": "hello there!" }' \
  https://app.talkus.io/api/visitor/message

The above command returns JSON structured like this:

{
  "ok": "true",
  "visitorId": "5rTdrc986vWm12"
}

Send a message from an existing visitor:

curl -X POST \
  --user '1234562a44147d1b3b3bad556784beae:' \
  -H 'Content-Type: application/json' \
  -d '{ "visitorId": "5rTdrc986vWm12", "text": "I need your help!" }' \
  https://app.talkus.io/api/visitor/message

The above command returns JSON structured like this:

{
  "ok": "true",
  "visitorId": "5rTdrc986vWm12"
}

If there’s an error, it’ll be like this:

{
  "ok": "false",
  "error": "No text"
}

POST https://app.talkus.io/api/visitor/message

Post a new visitor message to an exiting visitor (if you set the visitorId) or to a new visitor (in this case, the result will contains the visitorId).

This entrypoint is useful if you want to add a new channel (another SMS provider for example). When your external provider sends you a message coming from a visitor’s phone for example, call this entrypoint to create or update a ticket into Talkus (and so in Slack) with the visitor’s message.

If it’s a new visitor (you don’t have visitorId), call the entrypoint without visitorId so we’ll create a new one for you and return it. Then you store in your database the visitorId and phone number (or any other id you want) so next time this visitor sends you a message, you can provide the visitorId and Talkus will add the message to this existing visitor.

Parameters

Parameter	Options	Description
text	mandatory	The visitor’s message.
visitorId	optional	The id of the visitor. If not set, it’ll create a new visitor and returns the new id.
type	optional	The name or emoji (using long emoji format like `:poop:`) that will be displayed on the ticket.
identity	optional	A JSON object that containing information of the visitor. More information…

Commands

On Command page, you can create dot commands. A dot command always starts with a dot (.) and are executed only when typed inside a visitor channel (where you answer to your visitor). When you type a dot command, the visitor doesn’t see it but he’ll see the result of the command, except if the result starts with a double dot (..), in this case, the result will be only be visible to the agent.

Post a message

Most basic form of a dot command, when the agent execute the command, it displays the message entered in Value.

Useful to create canned responses.

Execute a Server command

Call a webhook on your server when the dot command is executed by the agent. It’s a POST requests on your server containing a JSON with all the information you need, agent who executed the command, on which visitor, the discussion.

You can reply to this POST either with:

"I am a test message"

a string, in this case, the string will be pushed in the discussion and so it’ll be displayed to the visitor. If you don’t want the visitor sees it, start the string with a double dot (..).

{
    "text": "I am a test message",
    "attachments": "[{ \"text\": \"And here's an attachment!\" }]"
}

a JSON object in the Slack format. So you can craft advanced messages with attachement and all other Slack formatting features.

For example, you can create a command .ban that will call your server and your server will ban the visitor on your product.

Another example, for an e-commerce website, can be .status that will find the status of the latest visitor order and returns it to the agent and / or visitor.

Execute a Client command

Execute the javascript code you entered in Value input in the browser of the visitor.

window.location.href = 'http://google.com';

If you use this code in a command called .google, when executed, it’ll redirect the visitor to google homepage.

Alias to another command

Alias a command with another one. For example by default, you have alias of end with e so instead of typing .end to close a discussion, you can just type .e.

Webhooks

Example of data sent to your webhook when an agent sends a message to a visitor.

[  
  {
    "event": "messageAgent",
    "createdAt": "2016-01-09T11:09:09.111Z",
    "channelName": "z-33123456789",
    "visitorName": "+33123456789",
    "visitorId": "a3W7EEfSWanTWyGkg",
    "identity": {
      "name": "Scarlet",
      "phone": "+33123456789",
      "email": "scar@let.com",
      "picture": "https://pbs.twimg.com/profile_images/714633747770044416/Qu8c4fje.jpg",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
      "title": "",
      "location": "http://localhost:8080/",
      "ip": "",
      "languages": "en"
    },
    "agent": {
      "id": "U0F2Z1234",
      "team_id": "T0F212345",
      "name": "moss",
      "deleted": false,
      "status": null,
      "color": "9f69e7",
      "real_name": "Moss",
      "tz": "Europe/Amsterdam",
      "tz_label": "Central European Time",
      "tz_offset": 3600,
      "profile": {
        "fields": [
        ],
        "first_name": "Moss",
        "last_name": "",
        "title": "",
        "phone": "(123) 555 555",
        "skype": "",
        "avatar_hash": "82b1244b9af",
        "image_24": "https://avatars.slack-edge.com/2016-11-25/109119461858_82b5e3bbb9af2724c0a4_24.jpg",
        "image_32": "https://avatars.slack-edge.com/2016-11-25/109119461858_82b5e3bbb9af2724c0a4_32.jpg",
        "image_48": "https://avatars.slack-edge.com/2016-11-25/109119461858_82b5e3bbb9af2724c0a4_48.jpg",
        "image_72": "https://avatars.slack-edge.com/2016-11-25/109119461858_82b5e3bbb9af2724c0a4_72.jpg",
        "image_192": "https://avatars.slack-edge.com/2016-11-25/109119461858_82b5e3bbb9af2724c0a4_72.jpg",
        "image_512": "https://avatars.slack-edge.com/2016-11-25/109119461858_82b5e3bbb9af2724c0a4_72.jpg",
        "image_1024": "https://avatars.slack-edge.com/2016-11-25/109119461858_82b5e3bbb9af2724c0a4_72.jpg",
        "image_original": "https://avatars.slack-edge.com/2016-11-25/109119461858_82b5e3bbb9af2724c0a4_original.jpg",
        "real_name": "Moss",
        "real_name_normalized": "Moss",
        "email": "moss@reynholm.com"
      },
      "is_admin": true,
      "is_owner": true,
      "is_primary_owner": true,
      "is_restricted": false,
      "is_ultra_restricted": false,
      "is_bot": false,
      "presence": "active"
    },
    "message": "+33123456789: \nHi! Do you have any doc to your API?\nMoss: Yes! Go to <http://developer.talkus.io/>",
    "messages": [  
      {
        "userName": "+33123456789",
        "userPicture": "https://pbs.twimg.com/profile_images/714633747770044416/Qu8c4fje.jpg",
        "createdAt": "2016-01-09T11:08:01.774Z",
        "text": "\nHi! Do you have any doc to your API?"
      },
      {
        "userName": "Moss",
        "userPicture": "https://avatars.slack-edge.com/2016-11-25/109119461858_82b5e3bbb9af2724c0a4_48.jpg",
        "createdAt": "2016-01-09T11:09:09.104Z",
        "text": "Yes! Go to <http://developer.talkus.io/>"
      }
    ]
  }
]

On the Integration page, you’ll have a webhook input.

Fill this input with an entry point on your server.

We’ll HTTP POST it with a JSON in the body containing information about the visitor, the agent and the whole conversation.

We call this webhook in these cases:

Name	Description
start	when a new conversation is starting.
open	when a conversation is opened (an agent entered the channel).
end	when a conversation is closed (.end called by the agent).
email	when the visitor entered its email.
messageVisitor	when a visitor sent a new message (`message` contains the visitor’s message).
messageAgent	when an agent sent a new message (`message` contains the agent’s message).

Javascript functions

talkus('commandName');

On the client side of the live chat plugin, you can add more javascript code after the Talkus snippet to interact with the plugin.

Init

Anonymous initialization:

talkus('init', 'yourappid');

This function must be the first one to call to initialize Talkus.

You can call it multiple times if you want to update the identity of the visitor. Useful for Single Page Application (SPA).

Initialization with identification of the visitor:

talkus('init', 'yourappid', {
  id: '1234'
  name: 'John Doe',
  email: 'john@doe.com',
  ...
});

If your visitor is logged, you often want to provide extra info to Talkus so your agents will be able to know who the visitor is.

To do that, you have to add a third parameter to the talkus('init') function that contains a javascript object.

This object can contains any keys/values you want but the following keys are used by Talkus to enhance the visitor:

Key	Value	Description
id	optional, must be unique	An unique string that is linked to this visitor. We’ll use it to identify the visitor in our database. So even if the visitor is on another computer or in incognito mode, you’ll have all the information about him. The id must be uniq per visitor.
name	optional, String	Name of the visitor. We’ll use it to name the visitor Slack channel.
email	optional, ‘john@doe.com’	Email address of the visitor. If you provide the email, Talkus will not ask the visitor for his email. If Talkus has the email but not the name, it’ll use the email to name the Slack channel. An email will be sent if the visitor leave a live chat.
phone	optional, ’+33123456789’	Phone number of the visitor. Talkus will use it to send SMS.
picture	optional, 'http://a.co/i.png’	The url to the picture of the visitor avatar. It’ll be displayed in your Slack channel.
tag	optional, 'pro’	You can programmatically tag ticket in the html code. Tagging is useful to separate different type of visitors or subdomains. For example, you can create a `pro` tag for pro visitors that needs instant support. All tickets will go to `#zz-pro` Slack channel instead of the default `#talkus-support` where you can set Slack notification to a higher level to never miss them.

You can add any other fields you want, they’ll be displayed in Slack visitor information. It can be useful for example to display if the visitor uses a free or paying plan, display a link to your backoffice for this visitor, …

Show

talkus('show');

Display Talkus button. By default, the button is displayed so you don’t need to call it.

Hide

talkus('hide');

Hide Talkus button.

Open

talkus('open');

Open Talkus plugin.

Close

talkus('close');

Close Talkus plugin.

News

talkus('news');

Open Talkus plugin on the news tab.

Faq

talkus('faq', 'query');

Open Talkus plugin on the faq tab and search for query.

FaqId

talkus('faqId', '1234567');

Open Talkus plugin on a specific faq entry using the Id of the faq.

Reset

talkus('reset');

Remove all cookies/localstorage information on the browser.

Callback

talkus('callback', function(name) {
  console.log('callback', name);
});

Receive event from Talkus. Add a callack Talkus will call when events occur.

Name	Parameters	Description
`notification`	nbNotification (Number)	Called when the visitor received a new notification (message from agents). `nbNotification` contains the number of notification (by default, it’s the number displayed in the red bubble on the top right of the Talkus button).
`open`		Called when the visitor opened the plugin.
`messageSend`	[texts]	Called when a message from the visitor is sent to the agent. `texts` is an array of string.

talkus('close');

will call your callback function with close as first parameter.

For each talkus(commandName) call, it’ll call your callback, Name will be commandName.

SendMessage

talkus('sendMessage', 'Hello');

Send to Talkus a message like if the visitor typed it.

External channels

Talkus has channels like live chat, email, sms, phone, twitter, facebook but you can add your own channel.

It can be useful to integrate in Talkus your own SMS provider, Snapchat or any other channel you want.

To do that, you need to implement 2 things:

Code a webhook in your server and add the url in the integration page so we can call your server when an agent posts a message (that you need to send to the visitor using your provider).
Call our sendMessage API we can create or update the visitor ticket when you receive a message from your visitor.