Setup and usage
The Web API supplies a collection of HTTP methods that underpin the majority of GB Talk functionality. To start using the Web API follow the tutorial below.
Usage
Make a POST call to the file script/include/api.php of us GB Talk installation. You can use the following code to make the calls:
function support_board_api($query) {
$ch = curl_init('https://chat.gbtalk.net/script/include/api.php');
$parameters = [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_SSL_VERIFYPEER => false,
CURLOPT_USERAGENT => 'GB Talk',
CURLOPT_POST => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_POSTFIELDS => http_build_query(array_merge(['token' => 'YOUR-TOKEN'], $query))
];
curl_setopt_array($ch, $parameters);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
$.post('https://chat.gbtalk.net/script/include/api.php', {
function: 'METHOD-NAME',
token: 'YOUR-TOKEN'
}, function (response) {
response = JSON.parse(response);
if (response.success) {
}
});
The variable $response will contains the JSON response. You can add new arguments in the query array: ['token' => '', 'function' => '', 'argument-name' => 'value', ...].
Replace the following strings with the correct values:
- The full URL must point to the file script/include/api.php It should looks like this: https://chat.gbtalk.net/script/include/api.php
- Replace YOUR-TOKEN with the token of an admin user. You can get the token from Account > Installation > API token. Warning! This token must be kept always secret.
- Replace METHOD-NAME with the name of the API function you want to use. Get them from the methods list below.
Information
- Some functions are protected for security reasons, contact the GB Talk Support.
Users
Methods to manage users, agents, and admins.
get-user
Returns the user details of a user.
Arguments
token |
Your admin secret token. |
function |
Insert get-user. |
user_id |
The ID of the user. |
extra |
Set it to true to get the additional user details. Default: false. |
Response
{
"success": true,
"response": {
"id": "123456",
"first_name": "Bianca",
"last_name": "Santos",
"email": "bianca@example.com",
"profile_image": "https://chat.gbtalk.net/script/uploads/12-05-20/3199409.png",
"user_type": "visitor",
"creation_time": "2020-05-12 14:28:57",
"last_activity": "2020-05-12 14:28:57",
"department": null,
"token": "a521773c5a566a251c3fb00e93162b20ff955b12",
"password": "",
"details": [
{
"slug": "location",
"name": "Location",
"value": "New York, United States"
},
{
"slug": "country_code",
"name": "Country code",
"value": "America/New_York"
}
...
]
}
}
Return {"success":true, "response":false} if the user is not found.
get-user-extra
Returns the additional details of a user.
Arguments
token |
Your admin secret token. |
function |
Insert get-user-extra. |
user_id |
The ID of the user. |
slug |
The slug of the setting to retrieve. If this argument is not set, all user details are returned. Default: false. |
default |
The default value to return if the user details are not found. Default: false. |
Response
{
"success": true,
"response": [
{
"slug": "browser",
"name": "Browser",
"value": "Chrome"
},
{
"slug": "current_url",
"name": "Current URL",
"value": "https://gbtalk.net/"
},
{
"slug": "os",
"name": "OS",
"value": "Windows 10"
},
{
"slug": "phone",
"name": "Phone",
"value": "3203057977"
}
...
]
}
Return {"success":true, "response":[]} if the user is not found.
get-user-language
Returns the active language code used by the user. By default, it's the user browser language.
Arguments
user_id |
The ID of the user from whom you want to get the language. |
Response
The language code. Examples: es, it. Returns false if the language code is en or not found.
get-users
Returns the user details of all the users.
Arguments
token |
Your admin secret token. |
function |
Insert get-users. |
sorting |
Set the order of the returned values. Insert ["column", "order"] and replace column with one of the following values: first_name, last_name, email, profile_image, user_type, creation_time, last_activity, department. Replace order with ASC or DESC. |
user_types |
Array in JSON format of user types to include in the return value. Array syntax: ["", "", "", ...]. Accepted values: visitor, lead, user, agent, admin. Default: all. |
search |
The string to search. |
pagination |
Integer from 1 to N to limit the results number. Insert 1 to get the first 100 results, 2 for the results from 101 to 200, etc. |
extra |
Set it to true to include all users extra details as well. Set it as an array of user extra detail slugs to include only a subset of extra details. Default: false. |
user_ids |
Array of IDs. If set, returns only the users with ID included in the given array of IDs. Array syntax: ["", "", "", ...]. Default: false. |
Response
{
"success": true,
"response": [
{
"id": "880",
"first_name": "User",
"last_name": "#29938",
"email": null,
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "visitor",
"creation_time": "2020-05-13 08:58:18",
"last_activity": "2020-05-13 09:07:39",
"department": null,
"token": "6d969f64f5ed6263714b9b39f3d3700b66f16820"
},
{
"id": "879",
"first_name": "User",
"last_name": "#86773",
"email": null,
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "visitor",
"creation_time": "2020-05-13 08:38:41",
"last_activity": "2020-05-13 08:58:12",
"department": null,
"token": "2e5064670707d06b661d04353f4a462ec927f19a"
}
...
]
}
get-new-users
Returns the users created after the given date/ID.
Arguments
token |
Your admin secret token. |
function |
Insert get-new-users. |
datetime |
User ID or date and time in the following format: YYYY-MM-DD HH:MM:SS. E.g. 2020-05-13 13:35:59. You can remove the time and leave only the date. The dates stored in the database are in UTC+0. |
Response
{
"success": true,
"response": [
{
"id": "880",
"first_name": "User",
"last_name": "#29938",
"email": null,
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "visitor",
"creation_time": "2020-05-13 08:58:18",
"last_activity": "2020-05-13 09:07:39",
"department": null,
"token": "6d969f64f5ed6263714b9b39f3d3700b66f16820"
},
{
"id": "879",
"first_name": "User",
"last_name": "#86773",
"email": null,
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "visitor",
"creation_time": "2020-05-13 08:38:41",
"last_activity": "2020-05-13 08:58:12",
"department": null,
"token": "2e5064670707d06b661d04353f4a462ec927f19a"
}
...
]
}
get-online-users
Returns the online users including Agents.
Arguments
token |
Your admin secret token. |
function |
Insert get-online-users. |
exclude_id |
Array of users IDs in JSON format to exclude from the returned values. Array syntax: [123, 123, 123, ...] |
sorting |
The name of the database table used for sorting. Default: creation_time. |
agents |
Set it to true to return only agents and admins. Default: false. |
Response
{
"success": true,
"response": [
{
"id": "881",
"first_name": "Don",
"last_name": "John",
"email": null,
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "visitor",
"creation_time": "2020-05-13 09:18:59",
"last_activity": "2020-05-13 09:32:34",
"department": null,
"token": "e435a5c67f4276cdb9c6fc19b7c015990ffc3268"
},
{
"id": "880",
"first_name": "User",
"last_name": "#29938",
"email": null,
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "visitor",
"creation_time": "2020-05-13 08:58:18",
"last_activity": "2020-05-13 09:32:28",
"department": null,
"token": "6d969f64f5ed6263714b9b39f3d3700b66f16820"
}
...
]
}
get-users-with-details
Returns an array with the user IDs and details of the users who have the requested details.
Arguments
token |
Your admin secret token. |
function |
Insert get-users-with-details. |
details |
Array of user details. E.g. [ "email", "phone" ]. |
user_ids |
Array, or comma-separated string of user IDs. If this argument is set only the users which have their ID included are returned. Set it to all or false to search all users, set it to agents to search only agents and admins. Default: false. |
Response
{
"email": [
{
"id": 4561,
"value": "albert@example.com"
},
{
"id": 98436,
"value": "jessica@example.com"
},
...
],
"phone": [
{
"id": 12563,
"value": "+4462367136"
},
{
"id": 778956,
"value": "+4462999345"
},
...
],
...
}
get-agent
Return the details of an agent or admin.
Arguments
token |
Your admin secret token. |
function |
Insert get-agent. |
agent_id |
The agent ID. |
Response
{
"success": true,
"response": {
"id": "123456",
"first_name": "John",
"last_name": "Doe",
"email": "johon@example.com",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "agent",
"creation_time": "2020-05-12 14:28:57",
"last_activity": "2020-05-12 14:28:57",
"department": null,
"token": "a521773c5a566a251c3fb00e93162b20ff955b12",
"password": "",
"details": [
{
"slug": "location",
"name": "Location",
"value": "New York, United States"
},
{
"slug": "country_code",
"name": "Country code",
"value": "America/New_York"
}
...
]
}
}
get-agents-ids
Returns an array with the IDs of Agents.
Arguments
token |
Your admin secret token. |
function |
Insert get-agents-ids. |
admins |
Set it to false to exclude the admins. Default: true; |
Response
[
881,
153,
...
]
get-user-from-conversation
Returns the user ID and email of the user, or last agent, of the given conversation.
Arguments
token |
Your admin secret token. |
function |
Insert get-user-from-conversation. |
conversation_id |
The conversation ID. |
agent |
Set it to true to get the last agent who replied to the conversation. Default: false. |
Response
{
"id": "123456",
"email": "email@example.com"
}
agents-online
Check if at least one agent or admin is online.
Response
{
"success": true,
"response": true
}
Return true if there are agents or admin online, or false if all Agents are offline.
search-users
Returns the users matching the search.
Arguments
token |
Your admin secret token. |
function |
Insert search-users. |
search |
The string to search. The additional user details are supported too. |
Response
{
"success": true,
"response": [
{
"id": "881",
"first_name": "Don",
"last_name": "John",
"email": null,
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "visitor",
"creation_time": "2020-05-13 09:18:59",
"last_activity": "2020-05-13 09:32:34",
"department": null,
"token": "e435a5c67f4276cdb9c6fc19b7c015990ffc3268"
},
{
"id": "880",
"first_name": "User",
"last_name": "#29938",
"email": null,
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "visitor",
"creation_time": "2020-05-13 08:58:18",
"last_activity": "2020-05-13 09:32:28",
"department": null,
"token": "6d969f64f5ed6263714b9b39f3d3700b66f16820"
}
...
]
}
Return {"success":true, "response":[]} if no users are found.
add-user
Create a new user.
Arguments
Response
{
"success": true,
"response": 123456
}
Other possible responses: ID of the new user on success, otherwise duplicate-email, invalid-user-type, MySQL error message.
update-user
Update the details of an existing user.
Arguments
token |
Your admin secret token. |
function |
Insert update-user. |
user_id |
The ID of the user to update. |
first_name |
The first name of the user. |
last_name |
The last name of the user. |
|
|
The email of the user. Insert NULL to delete the email. |
profile_image |
The profile picture of the user. |
password |
The password of the user. |
user_type |
The user type of the user. Accepted values: visitor, lead, user, agent, admin. |
settings_extra |
Array of additional user details in
JSON format.
Array syntax: {"ID": ["value", "Name"], "ID": ["value", "Name"], ...}
|
Response
{
"success": true,
"response": true
}
Other possible responses: duplicate-email, invalid-user-type, MySQL error message.
delete-user
Delete a user and all linked conversations and messages.
Arguments
token |
Your admin secret token. |
function |
Insert delete-user. |
user_id |
The ID of the user to delete. |
Response
{
"success": true,
"response": true
}
delete-users
Delete multiple users and all linked conversations and messages.
Arguments
token |
Your admin secret token. |
function |
Insert delete-users. |
user_ids |
Array of IDs of the users to delete. Array syntax: [123, 123, 123, ...] |
Response
{
"success": true,
"response": true
}
is-online
Check if a user is online.
Arguments
token |
Your admin secret token. |
function |
Insert is-online. |
user_id |
The ID of the user. |
Response
true if online, false if offline.
current-url
Get or set the current URL of a user or the last visited URL.
Arguments
token |
Your admin secret token. |
function |
Insert current-url. |
user_id |
The ID of the user |
url |
The URL to set as "Current URL". If this argument is set the function will only set the value and it will not return any URL. |
Response
{
"success": true,
"response": "https://gbtalk.net"
}
Return {"success":true,"response":false} if the URL is not found. Return {"success":true,"response":true} if the url argument is set.
count-users
Returns the total users' count grouped by user type.
Arguments
token |
Your admin secret token. |
function |
Insert count-users. |
Response
{
"success": true,
"response": {
"all": "335",
"lead": "288",
"user": "15",
"visitor": "28"
}
}
update-user-to-lead
Change the user type of a user to lead.
Arguments
token |
Your admin secret token. |
function |
Insert update-user-to-lead. |
user_id |
The ID of the user. |
Response
{
"success": true,
"response": true
}
get-avatar
Generate the user profile image by using the first letter of first name, and last name, save the image, and return the image URL.
Arguments
token |
Your admin secret token. |
function |
Insert get-avatar. |
first_name |
The first name of the user. |
last_name |
The last name of the user. |
Response
https://chat.gbtalk.net/script/uploads/13-04-21/9455859.png
get-bot-id
Returns the GB Talk bot ID.
Response
123
is-typing
Check if a user or an agent is typing a message in a conversation. This function will not work if Pusher is active.
Parameters
token |
Your admin secret token. |
function |
Insert is-typing |
user_id |
The ID of the user, or the agent, to check. |
conversation_id |
The ID of conversation to check. |
Response
Return true if the user is typing, otherwise, return false.
is-agent-typing
Check if an agent is typing a message in a conversation, and returns the agent details. This function will not work if Pusher is active.
Arguments
token |
Your admin secret token. |
function |
Insert is-agent-typing |
conversation_id |
The ID of conversation to check. |
Response
{
"id": "",
"first_name": "",
"last_name": ""
}
Return false if no agents are typing.
set-typing
Assign the typing status to a user or an agent relative to a conversation.
Parameters
token |
Your admin secret token. |
function |
Insert set-typing |
user_id |
The ID of the user, or the agent. |
conversation_id |
The ID of the conversation. |
Response
{
"success": true,
"response": true
}
login
Login a user or an agent. A user can logins in two ways: via email and password, or via user ID and token.
Parameters
token |
Your admin secret token. |
function |
Insert login |
|
|
The email of the user to login. If this attribute is set you need to set also the password. Default: empty string. |
password |
The password of the user to login. If this attribute is set you need to set also the email. Default: empty string. |
user_id |
The ID of the user to login. If this attribute is set you need to set also the token. Default: empty string. |
token |
The token of the user to login. If this attribute is set you need to set also the user ID. You can get the token from the Users area by opening the profile box of a user. Default: empty string. |
Response
[
{
"id": "913",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"first_name": "User",
"last_name": "#29902",
"email": null,
"user_type": "visitor",
"token": "9b25351047ee758aa97ee4868d130cc1ceb8decf"
},
"YXNkWGNSeTdtRTdDYVkxVG8wckN4YWF6V2s0Tk1mczBSVHdQbHBpOWdmejVUTTdOUUxEUENhdUVoYmROWn..."
]
The last value is the encrypted login data ready to be stored in the sb-login cookie. Use the function SBF.loginCookie(response[1]); to store it. Returns false if login is unsuccessful.
logout
Logout the logged-in user.
Parameters
token |
Your admin secret token. |
function |
Insert logout. |
Response
{
"success": true,
"response": true
}
The sb-login cookie must also be deleted from the user's browser.
update-login
Update the user details of the logged-in user. This function update all the user details, if a detail is not set it will be deleted from the database.
Parameters
token |
Your admin secret token. |
function |
Insert update-login. |
profile_image |
The profile image URL of the user. Default: empty string. |
first_name |
The first name of the user. Default: empty string. |
last_name |
The last name of the user. Default: empty string. |
|
|
The email of the user. Default: empty string. |
department |
Update the department of the user. This setting is used in the admin area. Default: empty string. |
Response
YXNkWGNSeTdtRTdDYVkxVG8wckN4YWF6V2s0Tk1mczBSVHdQbHBpOWdmejVUTTdOUUxEUENhdUVoYmROWn...
The response must be saved into the sb-login cookie of the user's browser.
delete-leads
Delete all leads, including all the linked conversations and messages.
Parameters
token |
Your admin secret token. |
function |
Insert delete-leads. |
Response
true
Conversations
Methods to manage conversations and messages.
get-conversation
Returns a conversation and the messages of the conversation.
Arguments
token |
Your admin secret token. |
function |
Insert get-conversation. |
conversation_id |
The ID of the conversation. |
user_id |
The ID of the user linked to the conversation. |
Response
{
"success": true,
"response": {
"messages": [
{
"id": "2044",
"user_id": "802",
"message": "Hello!",
"creation_time": "2020-05-0410:06:30",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "946",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "lead"
},
{
"id": "2045",
"user_id": "377",
"message": "Hello,howcanIhelp?",
"creation_time": "2020-05-0410:06:33",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "946",
"first_name": "Bruce",
"last_name": "Peterson",
"profile_image": "https://chat.gbtalk.net/script/uploads/agent.svg",
"user_type": "agent"
}
...
],
"details": {
"user_id": "802",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "lead",
"id": "946",
"title": "",
"conversation_time": "2020-05-0410:06:30",
"conversation_status_code": "3",
"department": null
}
}
}
Return {"success":true,"response":{"messages":[],"details":""}} if the conversation is not found.
get-conversations
Returns all the conversations. Each conversation includes the last message of the conversation.
Arguments
token |
Your admin secret token. |
function |
Insert get-conversations. |
pagination |
Integer from 1 to N to limit the results number. Insert 1 to get the first 100 results, 2 for the results from 101 to 200, etc. |
status_code |
The status code of the returned conversations. Default: all the conversations in the inbox, excluding the conversations in the trash and archive. Status codes: live = 0, waiting answer from user = 1, waiting answer from agent = 2, archive = 3, trash = 4. |
routing |
Set it to true if the queue or routing is active in Settings > Miscellaneous. Default: false. |
routing_unassigned |
Set it to true to also view the conversations not assignged to any agent. Default: false. |
department |
Returns only the conversations assigned to the provided department ID. |
source |
Returns only the conversations created from the provided source. Available sources: em (Email), tk (Ticket), wa (WhatsApp), fb (Facebook Messenger), ig (Instagram), tw (Twitter), wc (WeChat), tx (Text message). |
Response
{
"success": true,
"response": [
{
"id": "1431",
"user_id": "632",
"message": "Hello!",
"creation_time": "2020-04-24 10:53:35",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "764",
"message_user_type": "lead",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"conversation_status_code": "2",
"user_type": "lead"
},
{
"id": "1430",
"user_id": "631",
"message": "Hi! Can you help me?",
"creation_time": "2020-04-24 10:38:37",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "763",
"message_user_type": "lead",
"first_name": "Jessica",
"last_name": "Brenson",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"conversation_status_code": "2",
"user_type": "lead"
}
...
]
}
get-new-conversations
Returns the conversations created after the given date/ID or with a message created after the given date/ID. Each conversation includes the last message of the conversation.
Arguments
token |
Your admin secret token. |
function |
Insert get-new-conversations. |
datetime |
Conversation ID or date and time in the following format: YYYY-MM-DD HH:MM:SS. E.g. 2020-05-13 13:35:59. You can remove the time and leave only the date. The dates stored in the database are in UTC+0. |
routing |
Set it to true if the queue or routing is active in Settings > Miscellaneous. Default: false. |
routing_unassigned |
Set it to true to also view the conversations not assignged to any agent. Default: false. |
Response
{
"success": true,
"response": [
{
"id": "1431",
"user_id": "632",
"message": "Hello!",
"creation_time": "2020-04-24 10:53:35",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "764",
"message_user_type": "lead",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"conversation_status_code": "2",
"user_type": "lead"
},
{
"id": "1430",
"user_id": "631",
"message": "Hi! Can you help me?",
"creation_time": "2020-04-24 10:38:37",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "763",
"message_user_type": "lead",
"first_name": "Jessica",
"last_name": "Brenson",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"conversation_status_code": "2",
"user_type": "lead"
}
...
]
}
Return {"success":true, "response":[]} if no conversations are found.
get-user-conversations
Returns the conversations of a user. Each conversation includes the last message of the conversation.
Arguments
token |
Your admin secret token. |
function |
Insert get-user-conversations. |
user_id |
The ID of the user. |
exclude_id |
Exclude a conversation from the results. |
agents |
Set it to true if the user is an agent or admin. Default: false. |
Response
{
"success": true,
"response": [
{
"id": "2266",
"user_id": "377",
"message": "Hello, how are you?",
"creation_time": "2020-05-12 17:30:35",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "995",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "lead",
"conversation_status_code": "3"
},
{
"id": "2266",
"user_id": "5",
"message": "Please leave a feedback.",
"creation_time": "2020-05-12 17:30:35",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "995",
"first_name": "Adam",
"last_name": "Gates",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "agent",
"conversation_status_code": "3"
}
...
]
}
Return {"success":true, "response":[]} if no conversations are found.
get-new-user-conversations
Returns the user conversations created after the given date/ID or with a message created after the given date/ID. Each conversation includes the last message of the conversation.
Arguments
token |
Your admin secret token. |
function |
Insert get-new-user-conversations. |
user_id |
The ID of the user. |
datetime |
Conversation ID or date and time in the following format: YYYY-MM-DD HH:MM:SS. E.g. 2020-05-13 13:35:59. You can remove the time and leave only the date. The dates stored in the database are in UTC+0. |
Response
{
"success": true,
"response": [
{
"id": "2266",
"user_id": "377",
"message": "Hello, how are you?",
"creation_time": "2020-05-12 17:30:35",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "995",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "lead",
"conversation_status_code": "3"
},
{
"id": "2266",
"user_id": "5",
"message": "Please leave a feedback.",
"creation_time": "2020-05-12 17:30:35",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "995",
"first_name": "Adam",
"last_name": "Gates",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "agent",
"conversation_status_code": "3"
}
...
]
}
Return {"success":true, "response":[]} if no conversations are found.
search-conversations
Returns the conversations matching the search.
Arguments
token |
Your admin secret token. |
function |
Insert search-conversations. |
search |
The string to search. The search function search into the attachment's names, the messages, and the user email, first name and last name. |
Response
{
"success": true,
"response": [
{
"id": "2130",
"user_id": "806",
"message": "Hello! How can I help you?",
"creation_time": "2020-05-05 15:45:38",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "952",
"message_user_type": "admin",
"first_name": "User",
"last_name": "#24254",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"conversation_status_code": "4",
"user_type": "lead"
},
{
"id": "2127",
"user_id": "805",
"message": "Hi, I need help!",
"creation_time": "2020-05-05 08:12:57",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "951",
"message_user_type": "user",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"conversation_status_code": "0",
"user_type": "user"
}
...
]
}
Return {"success":true, "response":[]} if no conversations are found.
search-user-conversations
Returns the conversations of the given user ID that matches the search terms.
Arguments
token |
Your admin secret token. |
function |
Insert search-user-conversations. |
search |
The string to search. The search function supports attachment names, messages of the conversations, and the conversation title. |
id |
The ID of the user. |
Response
{
"success": true,
"response": [
{
"id": "3362",
"user_id": "2",
"message": "Hello! How can I help you?",
"creation_time": "2020-06-24 17:34:39",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "1364",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "lead",
"conversation_status_code": "0"
},
{
"id": "3345",
"user_id": "1195",
"message": "Hi, I need help!",
"creation_time": "2020-06-24 17:06:23",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "1363",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "lead",
"conversation_status_code": "2"
}
...
]
}
Return {"success":true, "response":[]} if no conversations are found.
new-conversation
Create a new conversation.
Arguments
token |
Your admin secret token. |
function |
Insert new-conversation. |
user_id |
The ID of the user linked to the conversation. |
status_code |
The status code of the conversation. Default: 0. Status codes: live = 0, waiting answer from user = 1, waiting answer from agent = 2, archive = 3, trash = 4. |
title |
The title of the conversation. Default: empty. |
department |
The ID of a department. You can get the IDs from Settings > Miscellaneous > Departments. Default: -1. |
agent_id |
The ID of the agent assigned to the conversation. Default: -1. |
source |
Set the conversation source. Default: false. |
extra |
Extra conversation values. Default: false. |
Response
{
"success": true,
"response": {
"messages": [],
"details": {
"user_id": "882",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "lead",
"id": "1007",
"title": "",
"conversation_time": "2020-05-15 12:51:39",
"conversation_status_code": "0",
"department": null
}
}
}
Other possible responses: Conversation details array on success, otherwise user-not-found, MySQL error message
update-conversation-status
Update the status code of a conversation.
Arguments
token |
Your admin secret token. |
function |
Insert update-conversation-status. |
conversation_id |
The ID of the conversation. |
status_code |
The status code of the conversation. Status codes: live = 0, waiting answer from user = 1, waiting answer from agent = 2, archive = 3, trash = 4. |
Response
{
"success": true,
"response": true
}
Return invalid-status-code if the status code is invalid.
update-conversation-department
Update the department of a conversation.
Arguments
token |
Your admin secret token. |
function |
Insert update-conversation-department. |
conversation_id |
The ID of the conversation to update. |
department |
The ID of a department. You can get the IDs from Settings > Miscellaneous > Departments. The department ID is not validated, so double-check it to make sure it exists. Set it to false to remove the department. |
message |
A string containing a message for the agents notifications. If set, an all the agents assigned to the new department will be notified via email, push notification, and SMS. |
Response
{
"success": true,
"response": true
}
update-conversation-agent
Assign or update the agent assigned to a conversation.
Arguments
token |
Your admin secret token. |
function |
Insert update-conversation-agent. |
conversation_id |
The ID of the conversation to update. |
agent_id |
The ID of a agent. Set it to false to remove the agent. |
message |
A string containing a message for the agent notifications. If set, the agent will be notified via email, push notification, and SMS. |
Response
{
"success": true,
"response": true
}
set-rating
Assign a rating to a conversation and optionally update a message of the conversation.
Arguments
token |
Your admin secret token. |
function |
Insert set-rating. |
settings |
Enter the following array in JSON format: { "settings" : { "conversation_id": "ID", "rating": "RATING" }}. Replace ID with the ID of the conversation to rate, replace rating with 1 for a positive rating or with 0 for a negative one. |
payload |
The payload of the message in JSON format. |
message_id |
The ID of the message to update. |
message |
The content of the message. |
user_id |
The ID of the user of the conversation linked to the message. |
Response
{
"success": true,
"response": true
}
get-rating
Get the ratings of the conversations assigned to an agent.
Arguments
token |
Your admin secret token. |
function |
Insert get-rating. |
user_id |
The ID of an agent. |
Response
{
"success": true,
"response": [4,2]
}
The response array: [count of positive ratings, count of negative ratings]. In the example above there are 4 positive ratings and 2 negative ratings.
get-new-messages
Returns the messages of a conversation created after the given date/ID.
Arguments
token |
Your admin secret token. |
function |
Insert get-new-messages. |
user_id |
The ID of the user of the conversation. |
conversation_id |
The ID of the conversation. |
datetime |
Message ID or date and time in the following format: YYYY-MM-DD HH:MM:SS. E.g. 2020-05-13 13:35:59. You can remove the time and leave only the date. The dates stored in the database are in UTC+0. |
Response
{
"success": true,
"response": [
{
"id": "2319",
"user_id": "377",
"message": "Welcome to our support chat!",
"creation_time": "2020-05-12 18:04:50",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "1004",
"first_name": "Virtual",
"last_name": "Agent",
"profile_image": "https://chat.gbtalk.net/script/uploads/bot.svg",
"user_type": "bot"
},
{
"id": "2320",
"user_id": "877",
"message": "Thank you! I need help.",
"creation_time": "2020-05-12 18:04:51",
"attachments": "",
"status_code": "0",
"payload": "",
"conversation_id": "1004",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "lead"
}
...
]
}
Return {"success":true, "response":[]} if no conversations are found.
send-message
Add a new message to an existing conversation.
Arguments
token |
Your admin secret token. |
function |
Insert send-message. |
user_id |
The ID of the user who sends the message. Use the API 'get-bot-id' to get the ID of the bot. |
conversation_id |
The ID of the conversation. |
message |
The content of the message. |
attachments |
Array of attachments in JSON format. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. It's up to you to upload attachments to a remote server, this argument only accepts the URL of the files already uploaded. Default: []. |
conversation_status_code |
The status code of the conversation. Status codes: live = 0, waiting answer from user = 1, waiting answer from agent = 2, archive = 3, trash = 4. Set it to skip to leave the current conversation status. |
payload |
Array in JSON format of additional information. You can insert any value. Array syntax: { "key": value, "key": value, ... }. |
queue |
Set it to true if the queue is active in Settings > Miscellaneous > Queue. Default: false. |
recipient_id |
The ID of the user who receive the message. Use this attribute to get the user language. |
Response
{
"success": true,
"response": {
"status": "success",
"message-id": 123456,
"queue": false,
"notifications": ["sms", "email"]
}
}
Other possible responses: invalid-status-code, MySQL error message. The notifications response include the notifications sent to the user or agents.
update-message
Update an existing message.
Arguments
token |
Your admin secret token. |
function |
Insert update-message. |
message_id |
The ID of the message. |
message |
The content of the message. |
attachments |
Array of attachments in JSON format. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. It's up to you to upload attachments to a remote server, this argument only accepts the URL of the files already uploaded. Default: []. |
payload |
Array in JSON format of additional information. You can insert any value. Array syntax: { "key": value, "key": value, ... }. |
Response
{
"success": true,
"response": true
}
delete-message
Delete an existing message.
Arguments
token |
Your admin secret token. |
function |
Insert delete-message. |
message_id |
The ID of the message to delete. |
Response
{
"success": true,
"response": true
}
update-messages-status
Update the status code of multiple messages to read.
Arguments
token |
Your admin secret token. |
function |
Insert update-messages-status. |
message_ids |
Array of message IDs in JSON format, e.g. [1, 212, 124]. |
user_id |
The ID of the user linked to the messages. Required to update the user's chat if Pusher is active. |
Response
{
"success": true,
"response": true
}
get-agents-in-conversation
Returns an array with all the agents with at least one message in the conversation.
Arguments
token |
Your admin secret token. |
function |
Insert get-agents-in-conversation. |
conversation_id |
The conversation ID. It can be an array of conversation IDs. |
Response
{
"1546": [
{
"id": 5463,
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"conversation_id": 1546
},
{
"id": 6413,
"first_name": "Steven",
"last_name": "Travolta",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"conversation_id": 1546
},
...
],
...
}
transcript
Export a conversation in a CSV or TXT file and returns the URL.
Arguments
token |
Your admin secret token. |
function |
Insert transcript . |
conversation_id |
The ID of the conversation to export. |
type |
Set it to csv to export the conversation as a CSV file, set it to txt to export the conversation as a text file, set it to false to use the type set in Settings > Admin > Transcript type. Default: false. |
Response
{
"success": true,
"response": "https://chat.gbtalk.net/script/uploads/conversation-1021.csv"
}
Return {"success":true, "response":false} if the conversation is not found.
direct-message
Sends a direct message.
Arguments
token |
Your admin secret token. |
function |
Insert direct-message . |
user_ids |
Array of user IDs, e.g. [45, 89, 65]. |
message |
The message. |
subject |
The subject. Required only for emails. Default: false. |
Response
{
"success": true,
"response": true
}
messaging-platforms-send-message
Sends a message to the messaging platform linked to the conversation. Available messaging platforms: Facebook Messenger, Instagram, WhatsApp, Twitter, Telegram, Google Business Messages, WeChat, LINE, Viber, Tickets, Emails, Text messages.
Arguments
token |
Your admin secret token. |
function |
Enter messaging-platforms-send-message. |
conversation_id |
The conversation ID. |
message |
The message. |
attachments |
Array of attachments in JSON format. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. It's up to you to upload attachments to a remote server, this argument only accepts the URL of the files already uploaded. |
user |
Associative array with { "id": 123, "profile_image": "https://example.com/image.jpg" } as values, or a user ID. |
source |
Associative array with { "source": SOURCE CODE } as value. Available source codes: em (Email), tk (Ticket), wa (WhatsApp), fb (Facebook Messenger), ig (Instagram), tw (Twitter), wc (WeChat), tx (Text message), gb (Google Business Messages), tg (Telegram), ln (LINE) vb (Viber). For Telegram the source must also include { "chat_id": "123456789" }. For Facebook Messenger the source must also include { "page_id": "123456789" }. |
Response
{
"success":true,
"response":true
}
count-conversations
Counts the number of conversations.
Arguments
token |
Your admin secret token. |
function |
Insert count-conversations . |
status_code |
If set, only the conversations with the specified status are counted. Status codes: live = 0, waiting answer from user = 1, waiting answer from agent = 2, archive = 3, trash = 4. Default: false. |
Response
{
"success": true,
"response": 123456
}
check-conversations-assignment
Checks if a list of conversations is assigned to a department or agent and returns only the conversation IDs that are assigned to that agent and/or department.
Arguments
token |
Your admin secret token. |
function |
Insert check-conversations-assignment. |
conversation_ids |
Array of IDs of the conversations to check, e.g. [45, 565, 68]. |
agent_id |
The agent ID. Default: false. |
department_id |
The department ID. Default: false. |
Response
{
"success": true,
"response": [1234, 5, ...]
}
More methods
Various methods that perform different actions.
send-email
Send an email to an existing user using the email templates of the Settings > Notifications area.
Arguments
token |
Your admin secret token. |
function |
Insert send-email. |
recipient_id |
The ID of the user to which send the email. |
message |
The message of the email. |
attachments |
Array of attachments in JSON format. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. It's up to you to upload attachments to a remote server, this argument only accepts the URL of the files already uploaded. Default: []. |
sender_id |
The ID of the sender user. Default: the active user ID. |
Response
{
"success": true,
"response": true
}
Other possible responses: missing-user-id-or-message, security-error, user-email-not-found, user-or-sender-not-found.
send-custom-email
Sends a generic email to an email address. The sender email and name are the ones set in Settings > Notifications > Email settings.
Arguments
token |
Your admin secret token. |
function |
Insert send-custom-email. |
to |
The email address. |
subject |
The email subject. |
message |
The message of the email. |
sender_suffix |
Append the provided text to the sender name. Default: empty. |
Response
true
email-piping
Runs the email piping synchronization with GB Talk and converts emails to chat messages.
Arguments
token |
Your admin secret token. |
function |
Insert email-piping. |
force |
Set it to true to the execution of the synchronization, by default the synchronization is executed a maximum of one time per minute. Default: false. |
Response
true
send-sms
Sends a text message to a user or agent. If the template argument is true, the message is translated automatically.
Arguments
token |
Your admin secret token. |
function |
Insert send-sms. |
message |
The text message. |
to |
The phone number. |
template |
Set it to false to send only the message without the template content. Default: the message is sent within the template of Settings > SMS notifications. |
conversation_id |
Set it if the message contains the URL parameter {conversation_url_parameter}. |
attachments |
Array of attachment. Array syntax: [["name", "link"], ["name", "link"], ...] or ["link", "link", ...]. Replace name with the name of the attachment and link with the full URL of the attachment. It's up to you to upload attachments to a remote server, this argument only accepts the URL of the files already uploaded. Default: false. |
Response
{
"sid": "SM1f0e8ae6ade43cb3c0ce4525424e404f",
"date_created": "Fri, 13 Aug 2010 01:16:24 +0000",
"date_updated": "Fri, 13 Aug 2010 01:16:24 +0000",
"date_sent": null,
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"to": "+15305431221",
"from": "+15104564545",
"body": "A Test Message",
"status": "queued",
"flags":["outbound"],
"api_version": "2010-04-01",
"price": null,
"uri": "\/2010-04-01\/Accounts\/ACXXXX\/Messages\/SM1f004f.json"
}
push-notification
Send a Push notification to an agent, a group of agents, or all agents. Push notifications must be enabled in the settings area.
Arguments
title |
The title of the notification. |
message |
The message text. |
icon |
The icon of the notification. Default: GB Talk icon or notifications icon. |
interest |
The following values are accepted:
|
conversation_id |
The ID of the conversation to open when the user clicks the notification. |
Response
{
"publishId": "pubid-781799f5-6el4-4789-bc60-ee293543781"
}
Return false it the Push notifications are disabled in the settings area.
get-setting
Returns a setting saved in the Settings area.
Arguments
token |
Your admin secret token. |
function |
Insert get-setting. |
setting |
The setting ID. |
Response
{
"success": true,
"response": {
"option": "value",
"option": "value",
...
}
}
get-settings
Returns an array with all the settings.
Arguments
token |
Your admin secret token. |
function |
Insert get-settings. |
Response
{
"success": true,
"response": {
"chat-manual-init": [
false,
"checkbox"
],
"chat-login-init": [
false,
"checkbox"
],
"init-dashboard": [
true,
"checkbox"
],
"chat-timetable-disable": [
false,
"checkbox"
],
"rtl": [
false,
"checkbox"
],
"front-auto-translations": [
true,
"checkbox"
],
...
}
}
save-settings
Save all settings.
Arguments
token |
Your admin secret token. |
function |
Insert save-settings. |
settings |
The settings array. Get it from get-settings. |
external_settings |
Settings saved to a dedicated row of the table sb_settings of the database. |
external_settings_translations |
Translations of the external settings. |
Response
{
"success": true,
"response": true
}
saved-replies
Returns an array with all the saved replies.
Arguments
token |
Your admin secret token. |
function |
Insert saved-replies. |
Response
{
"success": true,
"response": [
{
"reply-name": "hello",
"reply-text": "Hello! How can I help?"
},
{
"reply-name": "email",
"reply-text": "Our email is support@example.com."
},
...
]
}
get-articles
Returns an array with all the articles or a single article.
Arguments
token |
Your admin secret token. |
function |
Insert get-articles. |
id |
The ID of the article. The get the articles IDs, execute this method again without arguments. Default: -1. |
count |
The maximum number of returned articles. Default: all. |
full |
Boolean. Set it to true to get full length article contents. Default: false. |
categories |
Set it to true to get the array of all categories, in such a case the response is a double array, first item articles, second item categories. Set it to the category ID to get only the articles of the give category. Default: false. |
articles_language |
Get the articles in the language of the given language code. If there are no articles in the given language code, the articles in the default language are returned instead. Set it to all to get all the translations. Default: false. |
Response
{
"success": true,
"response": [
{
"id": "6P2Oq",
"title": "What's new with the API V2?",
"content": "The API V2 is the new iteration of o ...",
"link": "https://gbtalk.net",
"categories": ["K92kl"]
},
{
"title": "Should I move to the new system?",
"content": "Yes. The newest version of the Actions ...",
"link": "https://gbtalk.net",
"id": "qf7kD",
"categories": ["ols85"]
},
...
]
}
{
"success": true,
"response": {
"id": "6P2Oq",
"title": "What's new with the API V2?",
"content": "The API V2 is the new iteration of our developer API. The new API integrates...",
"link": "https://gbtalk.net",
"categories": ["K92kl"]
}
}
save-articles
Save all the articles. This function deletes all the existing articles and replace them with the ones of the given array.
Arguments
token |
Your admin secret token. |
function |
Insert save-articles. |
articles |
The array with the articles. Use the API
get-articles to get the articles array.
Array syntax:
{"articles": [{"id": "", "title": "", "content": "", "link":"", "categories": []}, ...]}
|
translations |
The array with the articles translations. Use the API
get-articles to get the articles array.
Array syntax:
{ "es": [{"id": "", "title": "", "content": "", "link":"", "categories": []}, ...], "it": [...], ...}
|
Response
{
"success": true,
"response": true
}
search-articles
Returns the articles matching the search.
Arguments
token |
Your admin secret token. |
function |
Insert search-articles. |
search |
The string to search. The search function supports title and content. |
articles_language |
Search only the articles in the language of the given language code. If there are no articles in the given language code, the search returns the articles in the default language. Set it to all to get all the translations. Default: false. |
Response
{
"success": true,
"response": [
{
"id": "6P2Oq",
"title": "What's new with the API V2?p",
"content": "The API V2 is the new iteration of o ...",
"link": "https://gbtalk.net",
"categories": ["K92kl"]
},
{
"title": "Should I move to the new API?",
"content": "Yes. The newest version (V2) of the Actions ...",
"link": "https://gbtalk.net",
"id": "qf7kD",
"categories": ["K92kl"]
},
...
]
}
Return {"success":true, "response":[]} if no articles are found.
get-articles-categories
Returns an array with all the articles categories.
Arguments
token |
Your admin secret token. |
function |
Insert get-articles-categories. |
Response
{
"success": true,
"response": [
{
"id": "Nv9PG",
"title": "Business"
},
{
"id": "csPVh",
"title": "Travel And Tourism"
},
{
"id": "pl5S7",
"title": "Finance"
},
...
]
}
save-articles-categories
Save or update the articles categories array.
Arguments
token |
Your admin secret token. |
function |
Insert save-articles-categories. |
categories |
Array of categories. Array syntax: [ { "id": "123456", "title": "Category name" }, { "id": "123456", "title": "Category name" }, ...]. Get the existing categories array with the method get-articles-categories. |
Response
true
article-ratings
Get the ratings of an article or add a new rating to it.
Arguments
token |
Your admin secret token. |
function |
Insert article-ratings. |
article_id |
The ID of the article. |
rating |
The rating to add. Insert 1 for a positive rating or 0 for a negative one. If this argument is set the method adds the rating, otherwise returns the existing ratings. Default: false. |
Response
{
"success": true,
"response": "[-1, 1, 1, -1]"
}
Returns true if the rating argument is set.
csv-users
Export all the users in a CSV file and returns the URL.
Arguments
token |
Your admin secret token. |
function |
Insert csv-users . |
Response
{
"success": true,
"response": "https://chat.gbtalk.net/script/uploads/users.csv"
}
pusher-trigger
Trigger an avent on a Pusher channel.
Arguments
token |
Your admin secret token. |
function |
Insert pusher-trigger |
channel |
The channel name. |
event |
The event name. |
data |
Array of values. Syntax: [ "name" => "value" ]. |
Response
true
text-formatting-to-html
Convert the text formatting of chat messages to the equivalent HTML codes and returns the message.
Arguments
token |
Your admin secret token. |
function |
Insert text-formatting-to-html |
message |
The text message. |
Response
Lorem ipsum dolor <b>sit amet</b>, <i>consectetur adipiscing elit</i>, <code>sed</code> do eiusmod tempor incididunt.
clear-text-formatting
Remove the text formatting from a chat messages.
Arguments
token |
Your admin secret token. |
function |
Insert clear-text-formatting |
message |
The text message. |
Response
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt.
get-notes
Returns the internal notes of a conversation.
Arguments
token |
Your admin secret token. |
function |
Insert get-notes |
conversation_id |
The conversation ID. |
Response
[
{
"id": 98207,
"user_id": "1538",
"name": "Lorem ipsum dolor sit amet",
"message": "Lorem ipsum dolor sit amet, consectetur elit, sed do eiusmod tempor incididunt."
},
{
"id": 76986,
"user_id": "1596",
"name": "Lorem ipsum dolor",
"message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor."
},
...
]
add-note
Add a new internal note.
Arguments
token |
Your admin secret token. |
function |
Insert add-note |
conversation_id |
The conversation ID to which link the note to. |
user_id |
The ID of the agent or admin who create the note. |
name |
The note name. |
message |
The note message. |
Response
The note ID
delete-note
Delete an internal note.
Arguments
token |
Your admin secret token. |
function |
Insert delete-note |
conversation_id |
The ID of the conversation linked with the note. |
note_id |
The note ID. |
Response
true
automations-get
Returns all automations.
Arguments
token |
Your admin secret token. |
function |
Insert automations-get |
Response
[
{
"emails": [
{
"id": "0BOaG",
"conditions": [
[
"datetime",
"is-between",
"10/04/2021 - 13/04/2021"
],
[
"include_urls",
"contains",
"https://example.com"
],
...
],
"name": "Excepteur sint",
"message": "Excepteur sint occaecat cupidatat non proident.",
"subject": "Cupidatat non proident"
},
...
],
"sms": [
{
"id": "vo2sY",
"conditions": [
[
"datetime",
"is-exactly",
"13/04/2021"
]
],
"name": "Excepteur sint",
"message": "Excepteur sint occaecat cupidatat non caecat cupidatat non proident"
},
{
"id": "hwkmQ",
"name": "Excepteur sint occaecat cupidatat non proident",
"message": "Excepteur sint occaecat cupidatat non occaecat cupidatat non proident"
},
...
],
"messages": [],
"popups": [
{
"id": "ckN24",
"conditions": [
[
"user_type",
"is-user"
],
[
"languages",
"en"
]
],
"name": "s",
"message": "Excepteur sint occaecat cupidatat non prcaecat cupidatat non proident",
"title": "Excepteur sint occaecat",
"profile_image": "https://example.com/image.jpg"
},
...
],
"design": [
{
"id": "bX1qA",
"conditions": [
[
"user_type",
"is-user"
]
],
"name": "Excepteur sint",
"message": "Excepteur sint occaecat cupidatat caecat cupidatat non proident",
"title": "",
"color_1": "rgb(0, 235, 26)",
"color_2": "rgb(255, 0, 0)",
"color_3": "rgb(255, 0, 0)",
"background": "https://example.com/image.jpg",
"brand": "https://example.com/image.jpg",
"icon": "https://example.com/image.jpg"
},
...
]
},
{
"fr": {
"messages": [
{
"id": "y6hNE",
"name": "XXXX",
"message": "XXXX"
}
]
},
...
}
]
automations-save
Save all automations.
Arguments
token |
Your admin secret token. |
function |
Insert automations-save |
automations |
Automations array. Get it from sb_get_automations(). |
translations |
Automations translations array. Get it from sb_get_automations(). |
Response
true
automations-validate
Validate an automations.
Arguments
token |
Your admin secret token. |
function |
Insert automations-validate |
automation |
The automation. |
Response
{
"conditions": [
[
"user_type",
"is-user"
],
...
],
"repeat_id": ""
}
Returns only the client-side conditions and invalid server-side conditions that can be validated in a later time. If no conditions are returned, the automation is valid and can be executed. Returns false if the automation is invalid.
automations-run-all
Validate all automations, execute the valid ones, and returns the automations with client-side conditions, invalid server-side conditions, and popup, design automations.
Arguments
token |
Your admin secret token. |
function |
Insert automations-run-all |
Response
[
{
"id": "0BOaG",
"conditions": [
[
"datetime",
"is-between",
"10/04/2021 - 13/04/2021"
],
[
"include_urls",
"contains",
"https://example.com"
],
...
],
"name": "Excepteur sint",
"message": "Excepteur sint occaecat cupidatat non proident.",
"subject": "Cupidatat non proident",
"type": "emails"
},
{
"id": "bX1qA",
"conditions": [
[
"user_type",
"is-user"
]
],
"name": "Excepteur sint",
"message": "Excepteur sint occaecat cupidatat caecat cupidatat non proident",
"title": "",
"color_1": "rgb(0, 235, 26)",
"color_2": "rgb(255, 0, 0)",
"color_3": "rgb(255, 0, 0)",
"background": "https://example.com/image.jpg",
"brand": "https://example.com/image.jpg",
"icon": "https://example.com/image.jpg",
"type": "design"
},
...
]
automations-run
Execute a single automation and optionally validate it before executing it.
Arguments
token |
Your admin secret token. |
function |
Insert automations-run |
automation |
The automation. |
validate |
Set it to true to validate the automation before executing it. Default: false. |
Response
true
clean-data
This function performs the following tasks: Delete visitors older than 24h. Delete messages in trash older than 30 days. Archive messages with an agent reply as last message older than 24h.
Requirements
- This is an admin function and it works only if the active user is an agent or an admin.
Parameters
token |
Your admin secret token. |
function |
Insert clean-data. |
Response
{
"success": true,
"response": true
}
get-departments
Returns the GB Talk departments.
Parameters
token |
Your admin secret token. |
function |
Insert get-departments. |
Response
{
"1": {
"name": "Example",
"color": "yellow",
"image": "https://example.com/image.png"
},
"2": {
"name": "Example",
"color": "red",
"image": "https://example.com/image.png"
},
...
}
reports
Returns the the specified reports.
Parameters
token |
Your admin secret token. |
function |
Insert reports. |
name |
The report name. Available values: conversations, missed-conversations, conversations-time, visitors, leads, users, agents-response-time, agents-conversations, agents-conversations-time, agents-ratings, countries, languages, browsers, os, subscribe, follow-up, registrations, articles-searches, articles-ratings, articles-views-single, articles-views, sms-automations, email-automations, message-automations, direct-sms, direct-emails, direct-messages. |
date_start |
The start date of the reports. Format: dd/mm/yyyy or yyyy-mm-dd. Default: false. |
date_end |
The end date of the reports. Format: dd/mm/yyyy or yyyy-mm-dd. Default: false. |
date_end |
The timezone of the user who is calling this function, e.g. Europe/London. Default: false. |
Response
{
"title": "Conversations count",
"description": "Count of new conversations started by users.",
"data": {
"03/2021": [
2
],
"04/2021": [
0
],
"05/2021": [
0
],
...
},
"table": [
"Date",
"Count"
],
"table-inverse": true,
"label_type": 1,
"chart_type": "line"
}
reports-update
Add a new row to the sb_reports database table.
Parameters
token |
Your admin secret token. |
function |
Insert reports-update. |
name |
The report name. Available values: conversations, missed-conversations, conversations-time, visitors, leads, users, agents-response-time, agents-conversations, agents-conversations-time, agents-ratings, countries, languages, browsers, os, subscribe, follow-up, registrations, articles-searches, articles-ratings, articles-views-single, articles-views, sms-automations, email-automations, message-automations, direct-sms, direct-emails, direct-messages. |
value |
The row value. Default: false. |
external_id |
An external ID. Default: false. |
extra |
An extr avalue. Default: false. |
Response
{
"success": true,
"response": true
}
export-settings
Exports the GB Talk settings in JSON format.
Parameters
token |
Your admin secret token. |
function |
Insert export-settings. |
Response
{
"success": true,
"response": "http://chat.gbtalk.net/script/uploads/settings_855776223.json"
}
Returns the URL of the JSON file containing the settings.
import-settings
Imports the GB Talk settings in JSON format.
Parameters
token |
Your admin secret token. |
function |
Insert import-settings. |
file_url |
The URL of the JSON file containing the settings. |
Response
{
"success": true,
"response": true
}
The WhatsApp app is required to use this set of APIs.
whatsapp-send-message
Sends a message to a WhatsApp number.
Arguments
token |
Your admin secret token. |
function |
Enter whatsapp-send-message. |
to |
The recipient's phone number. Include the country code. E.g. +39321305455 |
message |
The message. |
attachments |
Array of attachments in JSON format. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. It's up to you to upload attachments to a remote server, this argument only accepts the URL of the files already uploaded. Default: []. |
phone_id |
The phone number ID. Get it from Settings>WhatsApp. This setting is required only if you have synched multiple WhatsApp numbers. Default: false. |
Response
{
"success": true,
"response": {
"messaging_product": "whatsapp",
"contacts": [
{
"input": "+16315551234",
"wa_id": "+16315551234"
}
],
"messages": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI3N0EyQUJDMjFEQzZCQUMzODMA"
}
]
}
}
whatsapp-send-template
Sends a WhatsApp template to a WhatsApp number.
Arguments
token |
Your admin secret token. |
function |
Enter whatsapp-send-template. |
to |
The recipient's phone number. Include the country code. E.g. +39321305455 |
template_name |
The template name. Default: Settings>WhatsaApp>Cloud API template fallback>Template name. |
template_languages |
A comma separated string of all the available template language codes. E.g. en_US,it_IT. Default: Settings>WhatsaApp>Cloud API template fallback>Template languages. |
phone_id |
The phone number ID. Get it from Settings>WhatsaApp>Cloud API numbers. Default: false. |
parameters |
The template parameters array in JSON format. E.g. ["A", "B,C", "D,E"] The first array element are the header parameters, the second are the body parameters, and the third is the for button parameters. Each parameter is a string separated by a comma. Default: Settings>WhatsaApp>Cloud API template fallback. |
language |
The template language. Default: empty string. |
conversation_url_parameter |
Set it if the template text contains the {conversation_url_parameter} merge field. Default: empty string. |
user_name |
Set it if the template text contains the {recipient_name} merge field. |
user_email |
Set it if the template text contains the {recipient_email} merge field. |
recipient_id |
The Support Board user ID to which you are sending the template to. Default: false. |
Response
{
"success": true,
"response": {
"messaging_product": "whatsapp",
"contacts": [
{
"input": "+16315551234",
"wa_id": "+16315551234"
}
],
"messages": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI3N0EyQUJDMjFEQzZCQUMzODMA"
}
]
}
}
Messenger
The Messenger app is required to use this set of APIs.
messenger-send-message
Sends a message to Messenger or Instagram.
Arguments
token |
Your admin secret token. |
function |
Enter messenger-send-message. |
psid |
The PSID. To get this information, the user must first send you a message through Facebook. Get it by using the get-user function. |
facebook_page_id |
The Facebook Page ID. To get this information, the user must first send you a message through Facebook. Get it by using the get-conversation function. The ID is the extra value. |
message |
The message. |
attachments |
Array of attachments in JSON format. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. It's up to you to upload attachments to a remote server, this argument only accepts the URL of the files already uploaded. Default: []. |
metadata |
Provide the Support Board message ID linked to this message. Always include it when possible to avoid issues. Default: false. |
Response
{
"success": true,
"response": {
"recipient_id": "89995542233",
"message_id": "11445777889"
}
}
Telegram
The Telegram app is required to use this set of APIs.
telegram-send-message
Sends a message to Telegram.
Arguments
token |
Your admin secret token. |
function |
Enter telegram-send-message. |
chat_id |
The Chat ID. To get this information, the user must first send you a message through Telegram. Get it by using the get-conversation function. The ID is the extra value. |
message |
The message. |
attachments |
Array of attachments in JSON format. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. It's up to you to upload attachments to a remote server, this argument only accepts the URL of the files already uploaded. Default: []. |
conversation_id |
This setting is required only if you have synched multiple Telegram bots. Default: false. |
Response
{
"success": true,
"response": {
"ok": true,
"result": {
"message_id": 2030,
"from": {
"id": 21202173,
"is_bot": true,
"first_name": "Support Board",
"username": "sb_officialbot"
},
"chat": {
"id": 148766722,
"first_name": "Federico",
"last_name": "Schiocchet",
"username": "federicoschiocchet",
"type": "private"
},
"date": 1699621061,
"text": "Hello!"
}
}
}
Viber
The Viber app is required to use this set of APIs.
viber-send-message
Sends a message to Viber.
Arguments
token |
Your admin secret token. |
function |
Enter viber-send-message. |
viber_id |
The Viber ID. To get this information, the user must first send you a message through Telegram. Get it by using the get-user function. |
message |
The message. |
attachments |
Array of attachments in JSON format. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. It's up to you to upload attachments to a remote server, this argument only accepts the URL of the files already uploaded. Default: []. |
Response
{
"status": 0,
"status_message": "ok",
"message_token": 5741311803571721087,
"chat_hostname": "SN-CHAT-05_",
"billing_status": 1
}
LINE
The LINE app is required to use this set of APIs.
line-send-message
Sends a message to LINE.
Arguments
token |
Your admin secret token. |
function |
Enter line-send-message. |
line_id |
The LINE ID. To get this information, the user must first send you a message through LINE. Get it by using the get-user function. |
message |
The message. |
attachments |
Array of attachments in JSON format. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. It's up to you to upload attachments to a remote server, this argument only accepts the URL of the files already uploaded. Default: []. |
Response
{
"sentMessages": [
{
"id": "481156985669026149",
"quoteToken": "fKOxH1EKOAKYFLW6fe8vFGoKl2I2UZocU6KcoZgwtVrSTQjLbXFVer3Z-UV-aNkxE5BAct3WZOJpHBxEQavyVfkmsVMSou2KBNSFSEwtwuGkDwzEiUNsJ4V9WBR_leJef0KCxvP-OO1Ma5mxmt4rXg"
}
]
}
The WeChat app is required to use this set of APIs.
wechat-send-message
Sends a message to WeChat.
Arguments
token |
Your admin secret token. |
function |
Enter wechat-send-message. |
open_id |
The WeChat ID. To get this information, the user must first send you a message through LINE. Get it by using the get-user function. |
message |
The message. |
attachments |
Array of attachments in JSON format. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. It's up to you to upload attachments to a remote server, this argument only accepts the URL of the files already uploaded. Default: []. |
token |
The Google token. Get it from the response of this function. Always include it when possible for performance reasons. Default: false. |
Response
[
"{...}",
"5741311803571721087"
]
The first array element is the response, the second element is the token.
Webhooks
Webhooks are automated messages sent from GB Talk to a URL when something happens. They contain custom data and are sent to a unique URL defined by you.
Usage
- Login to the administration area and go to Settings > Miscellaneous > Webhooks.
- Enter the destination URL. GB Talk will send the data to this URL. This URL should point to a PHP file that can read the data received, you can use the code $response = json_decode(file_get_contents('php://input'), true); to get the data, the $response variable will be an array.
- Insert in the Secret Key field a secret password of your choice. This key is included in all the Webhooks, you can use it to validate the Webhook and make sure it is sent by GB Talk and not from someone else.
- Activate the Webhooks and save. GB Talk will now start sending the Webhooks of the list below to your URL.
- The key sender-url is included in all the Webhooks and contains the URL from which the webhook is sent.
- The setting Active webhooks defines what webhooks are active. Enter names of the webhooks separated by commas. Leave it empty to enable all webhooks.
message-sent
Webhook sent when a new message is sent by a user or an agent.
Response
{
"function": "message-sent",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": {
"user_id": "947",
"conversation_user_id": "947",
"conversation_id": "1057",
"conversation_status": "-1",
"message_id": "2574",
"message": "Hello! How are you?"
}
}
email-sent
Webhook sent when a notification email is sent to a user or to an agent.
Response
{
"function": "email-sent",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": {
"recipient_id": "957",
"message": "Hello! How can I help you?"
}
}
sms-sent
Webhook sent when a new text message is sent by a user or an agent.
Response
{
"function": "sms-sent",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": {
"recipent_id": "947",
"message": "Hello! How are you?",
"response": {
"sid": "SM1f0e8ae6ade43cb3c0ce4525424e404f",
"date_created": "Fri, 13 Aug 2010 01:16:24 +0000",
"date_updated": "Fri, 13 Aug 2010 01:16:24 +0000",
"date_sent": null,
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"to": "+15305431221",
"from": "+15104564545",
"body": "A Test Message",
"status": "queued",
"flags":["outbound"],
"api_version": "2010-04-01",
"price": null,
"uri": "\/2010-04-01\/Accounts\/ACXXXX\/Messages\/SM1f004f.json"
}
}
}
new-messages-received
Webhook sent when a new message is received.
Response
{
"function": "new-messages-received",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": [
{
"details": {
"id": "2575",
"user_id": "947",
"message": "Hello! How are you?",
"creation_time": "2020-05-27 08:26:59",
"attachments": "",
"status_code": "0",
"conversation_id": "1057",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "user",
"full_name": "Don John"
}
}
]
}
bot-message
Webhook sent when the Dialogflow send a reply to a user message.
Response
{
"function": "bot-message",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": {
"response": {
"token": "ya29.a0Afkjh8MADFYeT4BgCy3917xqSDdVvw4mgVHrgrLDcgRk9ajWoQAgdjv5e...",
"messages": [
{
"message": "Hi! How are you doing?"
}
],
"response": {
"responseId": "46d2c208-2a7f-4ca2-bd7d-6636982b8bee-0f0e27e1",
"queryResult": {
"queryText": "hi",
"action": "input.welcome",
"allRequiredParamsPresent": "true",
"fulfillmentText": "Hi! How are you doing?",
"fulfillmentMessages": [
{
"text": {
"text": [
"Hi! How are you doing?"
]
}
}
],
"outputContexts": [
{
"name": "projects/api-project-655517752147/agent/sessions...",
"lifespanCount": "1",
"parameters": {
"no-input": "0",
"no-match": "0"
}
}
],
"intent": {
"name": "projects/api-project-655517752147/agent/intents...",
"displayName": "Default Welcome Intent"
},
"intentDetectionConfidence": "1",
"languageCode": "en"
},
"alternativeQueryResults": [
{
"queryText": "hi",
"outputContexts": [
{
"name": "projects/api-project-655517752147/agent...",
"parameters": {
"no-match": "1",
"no-input": "0"
}
}
],
"languageCode": "en"
}
]
}
},
"message": "Hello",
"conversation_id": 123456
}
}
message-deleted
Webhook sent when a message is deleted.
Response
{
"function": "message-deleted",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": "2595"
}
The data key contains the ID of the deleted message.
rich-message
Webhook sent when the user submits the values inserted in a Rich Message. All the Rich Messages that require the submitting of data fire this Webhook, some of them are the follow-up email form, the registration form, the buttons.
Response
{
"function": "rich-message",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": {
"result": true,
"data": {
"type": "inputs",
"result": {
"name": [
"Don Jhon",
"Name"
],
"your-email": [
"example@gmail.com",
"Your Email"
],
"site-url": [
"www.example.com",
"Site URL"
],
...
}
},
"id": "example"
}
}
}
new-conversation
Webhook sent when a new conversation is received.
Response
{
"function": "new-conversation-received",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": {
"details": {
"user_id": "947",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "user",
"id": "1057",
"title": "",
"conversation_time": "2020-05-27 08:19:18",
"conversation_status_code": "2",
"department": "",
"agent_id": ""
}
}
}
new-conversation-created
Webhook sent when a user starts a new conversation.
Response
{
"function": "new-conversation-created",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": {
"details": {
"user_id": "947",
"first_name": "Don",
"last_name": "John",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"user_type": "user",
"id": "1057",
"title": "",
"conversation_time": "2020-05-27 08:19:18",
"conversation_status_code": "2",
"department": "",
"agent_id": ""
}
}
}
conversation-status-updated
Webhook sent when the status code of a conversation changes.
Response
{
"function": "conversation-status-updated",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": {
"conversation_id": "1057",
"status_code": "0"
}
}
Status codes: live = 0, waiting answer from user = 1, waiting answer from agent = 2, archive = 3, trash = 4.
login
Webhook sent when a user login successfully from the login form of the chat. This Webhook is sent only if the login is successful.
Response
{
"function": "login",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": {
"details": {
"id": "948",
"profile_image": "https://chat.gbtalk.net/script/uploads/user.svg",
"first_name": "Don",
"last_name": "John",
"email": "email@example.com",
"user_type": "user",
"token": "9a4642dd232291ad658646bdbb8792c2392bb852"
}
}
}
registration
Webhook sent when a user registers successfully from the registration form of the chat. This Webhook is sent only if the registration is successful. This Webhook is sent also if the registration is updated via the registration form of a Rich Message.
Response
{
"function": "registration",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": {
"user": {
"profile_image": [
"https://chat.gbtalk.net/script/uploads/user.svg",
"Profile image"
],
"first_name": [
"Don",
"First name"
],
"last_name": [
"John",
"Last name"
],
"email": [
"example@email.com",
"Email"
],
"password": [
"12345678",
"Password"
],
"password-check": [
"12345678",
"Repeat password"
],
"user_type": [
"user",
""
]
},
"extra": {
"phone": [
"+02123456789",
"Phone"
],
"city": [
"London",
"City"
],
...
}
}
}
user-deleted
Webhook sent when a user is deleted.
Response
{
"function": "user-deleted",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": "951"
}
The data key contains the ID of the deleted user.
new-email-address
Webhook sent when a user register his email via the follow-up message or registration form.
Response
{
"function": "new-email-address",
"key": "xxxxxxxx",
"sender-url": "https://example.com"
"data": {
"name": "John Doe",
"email": "example@email.com"
}
}