Getting started

Setup and usage

Setup and usage

The PHP API supplies a collection of PHP functions that underpin the majority of Brainy Assistant functionality. To start using the PHP API follow the steps below.

Usage

Include the file functions.php in your PHP file. The file is located in the include folder of the plugin folder. You're done! You can start using the functions of this documentation.

                                require("include/functions.php");
                            

Get the absolute path of your Brainy Assistant installation from Settings > Miscellaneous > Get Path. You can also use the variable $_SERVER["DOCUMENT_ROOT"]. Ex. require($_SERVER["DOCUMENT_ROOT"] . "/supportboard/include/functions.php");

Information

  • Some functions are protected for security reasons, enter the code $GLOBALS['SB_FORCE_ADMIN'] = true before calling the function to execute it correctly. Enter the code $GLOBALS['SB_FORCE_ADMIN'] = false immedidately after the function call for security reasons.
  • Some functions require the user details of the active user, use the code $GLOBALS['SB_LOGIN'] = ['id' => '', 'first_name' => '', 'last_name' => '', 'email' => '', 'user_type' => '', 'department' => '']; to set the active user.

PHP API

Users

Functions to manage users, agents, and admins.


sb_login()

Users

Log in a user or an agent. The login can be completed in two ways: via email and password, or user ID and token.


Arguments

email
The email of the user to log in. If this attribute is set you need to set also the password. Default: empty string.
password
The password of the user to log in. If this attribute is set you need to set also the email. Default: empty string.
user_id
The ID of the user to log in. If this attribute is set you need to set also the token. Default: empty string.
token
The token of the user to log in. 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://brainyassistant.com/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 Web Storage of the user' browser. Returns false if the login is unsuccessful.


sb_logout()

Log out the logged-in user, only on the server-side.


Response

true

This function logout the user only from the server. Use the Javascript API function SBF.logout(); to log out the user also in the client-side.


sb_get_active_user()

Returns the user details of the logged-in user.


Arguments

db
Set it to true to check if the user exists in the database. Default: false.
login_app
Encrypted array with the email and password of the logged-in WordPress user. This argument is used only in the WordPress version. If set, the function returns the logged-in WordPress user. Use this code to generate the array: sb_encryption(json_encode(['id' => "", 'email' => "")). Default: false.

Response

                                [
                                    {
                                        "id": "913",
                                        "profile_image": "https://brainyassistant.com/user.svg",
                                        "first_name": "User",
                                        "last_name": "#29902",
                                        "email": null,
                                        "user_type": "visitor",
                                        "token": "9b25351047ee758aa97ee4868d130cc1ceb8decf"
                                    },
                                    "YXNkWGNSeTdtRTdDYVkxVG8wckN4YWF6V2s0Tk1mczBSVHdQbHBpOWdmejVUTTdOUUxEUENhdUVoYmROWn..."
                                ]
                            

sb_get_user()

Returns the user details of the given user ID.


Arguments

user_id
The ID of the user.
extra
Set it to true to get also the extra user details. Default: false.

Response

                                {
                                    "id": "123456",
                                    "first_name": "John",
                                    "last_name": "Doe",
                                    "email": "johon@example.com",
                                    "profile_image": "https://brainyassistant.com/user.svg",
                                    "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"
                                        },
                                        ...
                                    ]
                                }
                            

sb_get_user_extra()

Returns the extra user details of the given user ID, or the requested one.


Arguments

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

                                [
                                    {
                                        "slug": "browser",
                                        "name": "Browser",
                                        "value": "Chrome"
                                    },
                                    {
                                        "slug": "current_url",
                                        "name": "Current URL",
                                        "value": "https://brainyassistant.com/"
                                    },
                                    {
                                        "slug": "os",
                                        "name": "OS",
                                        "value": "Windows 10"
                                    },
                                    {
                                        "slug": "phone",
                                        "name": "Phone",
                                        "value": "3203057977"
                                    },
                                    ...
                                ]
                            

sb_get_user_name()

Returns the full name of the active user, or the given one.


Arguments

user
The user object.

Response

The user name string

sb_get_users()

Returns the user details of all the users.


Arguments

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 returned value. Array syntax: ["", "", "", ...]. Accepted values: visitor, lead, user, agent, admin. Default: all.
search
String with the search terms.
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. Default: false.

Response

                                [
                                    {
                                        "id": "880",
                                        "first_name": "User",
                                        "last_name": "#29938",
                                        "email": null,
                                        "profile_image": "https://brainyassistant.com/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://brainyassistant.com/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"
                                    },
                                    ...
                                ]
                            

sb_get_new_users()

Returns the users created after the given date/ID.


Arguments

datetime
User ID or date and time in the following format: YYYY-MM-DD HH:MM:SS. Ex. 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

                                [
                                    {
                                        "id": "880",
                                        "first_name": "User",
                                        "last_name": "#29938",
                                        "email": null,
                                        "profile_image": "https://brainyassistant.com/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://brainyassistant.com/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"
                                    },
                                    ...
                                ]
                            

sb_get_online_users()

Returns the online users or the online agents and admins.


Arguments

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

                                [
                                    {
                                        "id": "881",
                                        "first_name": "Don",
                                        "last_name": "John",
                                        "email": null,
                                        "profile_image": "https://brainyassistant.com/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://brainyassistant.com/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"
                                    }
                                    ...
                                ]
                            

sb_get_online_user_ids()

Returns an array with the IDs of the online users and agents.


Arguments

agents
Set it to true to return only agents and admins. Default: false.

Response

                                [ 881, 548, 125, ... ]
                            

sb_get_users_with_details()

Returns an array with the user IDs and details of the users who have the requested details.


Arguments

details
Array of user details. Ex. [ "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"
                                        },
                                        ...
                                    ],
                                    ...
                                } 
                            

sb_get_agents_ids()

Returns an array with the IDs of Agents.


Arguments

admins
Set it to false to exclude the admins. Default: true;

Response

                                [
                                    881,
                                    153,
                                    ...
                                ]
                            

sb_search_users()

Returns the users matching the search.


Arguments

search
String with the search terms. Additional user details are supported too.

Response

                                [
                                    {
                                        "id": "881",
                                        "first_name": "Don",
                                        "last_name": "John",
                                        "email": null,
                                        "profile_image": "https://brainyassistant.com/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://brainyassistant.com/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"
                                    },
                                    ...
                                ]
                            

sb_add_user()

Create a new user.


Arguments

settings
Array with the user details. Array keys and syntax: [ "profile_image" => "", "first_name" => "", "last_name" => "", "email" => "", "password" => "", "user_type" => "", "department" => "" ]. Accepted user_type values: visitor, lead, user, agent, admin. Default: visitor if the email is not provided, otherwise, user.
settings_extra
Array of additional user details. Array syntax: ["key" => ["value", "Name"], "key" => ["value", "Name"], ...]. Any detail is accepted. Built-in details (keys): phone, city, language, country, birthday, company, facebook, twitter, linkedin, website, ip, country_code, browser, currency, location, os, time_zone, current_url.
login_app
Encrypted array with the email and password of the logged-in WordPress user. This argument is used only in the WordPress version. If set, the new user will use the user details of the given WordPress user ID. Use this code to generate the array: sb_encryption(json_encode(['id' => "", 'email' => "")). Default: false.
hash_password
Set it to false to skip the password hashing. Use this setting if the passowrd is already hashed. Default: true.

Response

                                123456
                            

Responses: ID of the new user on success, otherwise, duplicate-email, invalid-user-type, SQL error message.


sb_add_user_and_login()

Create a new user, log in it, and returns the login data for the client-side.


Arguments

This function uses the same arguments of the sb_add_user() function.


Response

This function returns the same response of the sb_login() function.


sb_add_new_user_extra()

Add additional user details to the user of the given ID. Existing user details will not be updated.


Arguments

user_id
The ID of the user to update.
settings
Array of additional user details. Array syntax: ["key" => ["value", "Name"], "key" => ["value", "Name"], ...]. Any detail is accepted. Built-in details (keys): phone, city, language, country, birthday, company, facebook, twitter, linkedin, website, ip, country_code, browser, currency, location, os, time_zone, current_url.

Response

                                true
                            

sb_update_user()

Update the details of an existing user.


Arguments

user_id
Enter the ID of the user to update.
settings
Array with the user details. Array keys and syntax: [ "profile_image" => "", "first_name" => "", "last_name" => "", "email" => "", "password" => "", "user_type" => "", "department" => "" ]. Accepted user_type values: visitor, lead, user, agent, admin. Default: visitor if the email is not provided, otherwise, user.
settings_extra
Array of additional user details. Array syntax: ["key" => ["value", "Name"], "key" => ["value", "Name"], ...]. Any detail is accepted. Built-in details (keys): phone, city, language, country, birthday, company, facebook, twitter, linkedin, website, ip, country_code, browser, currency, location, os, time_zone, current_url.
hash_password
Set it to false to skip the password hashing. Use this setting if the passowrd is already hashed. Default: true.

Response

                                true
                            

Other possible responses: duplicate-email, invalid-user-type, SQL error message.


sb_update_user_value()

Update a single detail, or extra detail, of an existing user, agent, or admin.


Arguments

user_id
The ID of the user to update.
slug
The unique name of the detail. Ex. first_name, email, city, birthday.
value
The new value of the detail.
name
The name of the extra detail. Required only if the user detail to update is an extra detail.

Response

                                true
                            

sb_update_login()

Update the login details of the logged-in user and returns the login data for the client-side. Use the Javascript API function SBF.loginCookie(response); to update the login details also in the client-side, the response is the response data returned by this function.


Arguments

profile_image
The URL of the profile image of the user.
first_name
The first name of the user.
last_name
The last name of the user.
email
The email of the user.
department
The ID of the department of the user. You can get the IDs from Settings > Miscellaneous > Departments. No department ID validation is performed, so double-check the department ID to be sure it exists.

Response

                                YXNkWGNSeTdtRTdDYVkxVG8wckN4YWF6V2s0Tk1mczBSVHdQbHBpOWdmejVUTTdOUUxEUENhdUVoYmROWn...
                            

sb_delete_user()

Delete a user and all the linked conversations and messages.


Arguments

user_id
The ID of the user to delete.

Response

                                true
                            

sb_delete_users()

Delete multiple users and all the linked conversations and messages.


Arguments

user_ids
Array of IDs of the users to delete. Array syntax: [123, 123, 123, ...]

Response

                                true
                            

sb_delete_leads()

Delete all leads, including all the linked conversations and messages.


Response

                                true
                            

sb_current_url()

Get or set the current URL of the user or the last visited URL.


Arguments

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

                                https://brainyassistant.com
                            

Return false if the URL is not found. Return true if the url argument is set.


sb_count_users()

Returns the total users' count grouped by user type.


Response

                                {
                                    "all": "335",
                                    "lead": "288",
                                    "user": "15",
                                    "visitor": "28"
                                }
                            

sb_update_user_to_lead()

Change the user type to lead.


Arguments

user_id
The ID of the user.

Response

                                true
                            

sb_slack_users()

Returns the agents-slack members' connection information. The Slack App is required.


Response

                                {
                                    "slack_users": [
                                        {
                                            "id": "U328T701Z",
                                            "name": "Support Schio"
                                        },
                                        {
                                            "id": "UR5F0GK7T",
                                            "name": "Robert Pitt"
                                        }
                                        ...
                                    ],
                                    "agents": [
                                        {
                                            "id": "2",
                                            "name": "Alex Smith"
                                        },
                                        {
                                            "id": "445",
                                            "name": "Federico Schiocchet"
                                        },
                                        {
                                            "id": "724",
                                            "name": "Alberto Prade"
                                        }
                                        ...
                                    ],
                                    "saved": {
                                        "U328T701Z": "445",
                                        "UR5F0GK7T": "2"
                                        ...
                                    }
                                }
                            

Response

                                true
                            

sb_is_agent()

Check if the given user type string is an admin, an agent, or the bot.


Arguments

user
A Brainy Assistant user, or a string.
exclude_bot
Set it to true to return false if the active user is the bot. Default: false.
exclude_bot
Set it to true to return true only if the active user is an administrator. Default: false.

Response

Return true if the user type string is "admin", "agent", or "bot", otherwise return false.


sb_supervisor()

Check if the active admin is the supervisor and return the supervisor settings if true.


Response

Return the supervisor settings if the active agent ID is the same of the one set in Settings > Admin > Supervisor > Admin ID, otherwise returns false.


sb_get_department()

Returns the department of the active user. This function is used in the admin area.


Response

Returns the department ID if set, otherwise, return false.


sb_password_verify()

Check if the given password matches the given password hash. The password hash is saved in the database in the password column of the sb_users table.


Arguments

password
The password to check.
hash
The password hash.

Response

Return true if the password matches the hash, otherwise, return false.


sb_user_autodata()

Add the following user details to the active user: city, location, country, timezone, currency, browser, browser language, os. These details are generated automatically.


Arguments

user_id
The ID of the active user.

Response

                                true
                            

sb_is_typing()

Check if a user or an agent is typing a message in a conversation.


Parameters

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.


sb_is_agent_typing()

Check if an agent is typing a message in a conversation, and returns the agent details.


Parameters

conversation_id
The ID of conversation to check.

Response

                                {
                                  "id": "",
                                  "first_name": "",
                                  "last_name": ""
                                }
                            

Return false if no agents are typing.


sb_set_typing()

Assign the typing status to a user or an agent relative to a conversation.


Parameters

user_id
The ID of the user or the agent.
conversation_id
The ID of conversation.
source
Array to set the typing status on external services. Facebook Messenger: ['fb', USER-ID, FB-PAGE-ID].

Response

                                true
                            

sb_is_online()

Check if the given date and time are recognized as online by Brainy Assistant.


Arguments

datetime
Date and time in the following format: YYYY-MM-DD HH:MM:SS. Ex. 2020-05-13 13:35:59. You can remove the time and leave only the date.

Response

true if online, false if offline.


sb_is_user_online()

Check if the user is online. This function is compatible with Pusher and Slack.


Arguments

user_id
The user ID.

Response

true if online, false if offline.


sb_agents_online()

Check if at least one agent or admin is online.


Response

true if there are agents or admin online, or false if all Agents are offline.


sb_get_bot_id()

Returns the ID of the bot.


Response

                                123456
                            

sb_get_user_from_conversation()

Returns the details of the user, or last agent, of the given conversation.


Arguments

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"
                                }
                            

sb_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

first_name
The first name of the user.
last_name
The last name of the user.

Response

                                https://example.com/supportboard/uploads/13-04-21/9455859.png
                            

sb_get_active_user_ID()

Returns the ID of the active user.


Response

The User ID.


sb_get_user_by

Return user info by a given field.


Arguments

by
The field. Accepted values: email, first_name, last_name, phone, [exta]. [extra] is any user additional detail slug.
value
The value of the field.

Response

                                {
                                    "id": "881",
                                    "first_name": "Don",
                                    "last_name": "John",
                                    "email": "example@example.com",
                                    "user_type": "visitor",
                                    "department": null
                                 }
                            

PHP API

Conversations

Conversations

Functions to manage conversations and messages.


sb_get_conversation()

Returns a conversation and the messages of the conversation.


Arguments

user_id
The ID of the user linked to the conversation.
conversation_id
The ID of the conversation.

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://brainyassistant.com/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://brainyassistant.com/agent.svg",
                                            "user_type": "agent"
                                        },
                                        ...
                                    ],
                                    "details": {
                                        "user_id": "802",
                                        "first_name": "Don",
                                        "last_name": "John",
                                        "profile_image": "https://brainyassistant.com/user.svg",
                                        "user_type": "lead",
                                        "id": "946",
                                        "title": "",
                                        "conversation_time": "2020-05-0410:06:30",
                                        "conversation_status_code": "3",
                                        "department": null
                                    }
                                }
                            

sb_get_conversations()

Returns all the conversations. Each conversation includes the last message of the conversation.


Arguments

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 conversations in trash and archive. Status codes: live = 0, waiting answer from user = 1, waiting answer from agent = 2, archive = 3, trash = 4.
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), gb (Google Business Messages).

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://brainyassistant.com/media/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://brainyassistant.com/media/user.svg",
                                        "conversation_status_code": "2",
                                        "user_type": "lead"
                                    },
                                    ...
                                ]
                            

sb_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

datetime
Conversation ID or date and time in the following format: YYYY-MM-DD HH:MM:SS. Ex. 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

                                [
                                    {
                                        "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://brainyassistant.com/media/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://brainyassistant.com/media/user.svg",
                                        "conversation_status_code": "2",
                                        "user_type": "lead"
                                    },
                                    ...
                                ]
                            

sb_get_user_conversations()

Returns the conversations of a user. Each conversation includes the last message of the conversation.


Arguments

user_id
The ID of the user of the conversations to get.
exclude_id
Exclude a conversation from the results.
agents
Set it to true if the user is an agent or admin. Default: false.

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://brainyassistant.com/media/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://brainyassistant.com/media/user.svg",
                                        "user_type": "agent",
                                        "conversation_status_code": "3"
                                    },
                                    ...
                                ]
                            

sb_get_last_conversation_id_or_create()

Returns the ID of the last user conversation if any, otherwise create a new conversation and returns its ID.


Arguments

user_id
The ID of the user.
conversation_status_code
The status code of the conversation to create if not conversations are found. Status codes: live = 0, waiting answer from user = 1, waiting answer from agent = 2, archive = 3, trash = 4.

Response

The conversation ID


sb_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

user_id
The ID of the user of the conversations to get.
datetime
Conversation ID or date and time in the following format: YYYY-MM-DD HH:MM:SS. Ex. 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

                                [
                                    {
                                        "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://brainyassistant.com/media/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://brainyassistant.com/media/user.svg",
                                        "user_type": "agent",
                                        "conversation_status_code": "3"
                                    },
                                    ...
                                ]
                            

sb_search_conversations()

Returns the conversations matching the search terms.


Arguments

search
String with the search terms. The search function supports attachment names, messages of the conversations, user email, and name of a message of the conversation.

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://brainyassistant.com/media/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://brainyassistant.com/media/user.svg",
                                      "conversation_status_code": "0",
                                      "user_type": "user"
                                    },
                                    ...
                                ]
                            

sb_search_user_conversations()

Returns the conversations of the active user or given user ID that matches the search terms.


Arguments

search
String with the search terms. The search function supports attachment names, messages of the conversations, and the conversation title.
id
The ID of the user. Default: active user ID

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://brainyassistant.com/media/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://brainyassistant.com/media/user.svg",
                                        "user_type": "lead",
                                        "conversation_status_code": "2"
                                    },
                                    ...
                                ]
                            

sb_new_conversation()

Create a new conversation.


Arguments

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 string.
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

                                {
                                    "messages": [],
                                    "details": {
                                        "user_id": "882",
                                        "first_name": "Don",
                                        "last_name": "John",
                                        "profile_image": "https://brainyassistant.com/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, SQL error message


sb_update_conversation_status()

Update the status code of a conversation.


Arguments

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

                                true
                            

Return invalid-status-code if the status code is invalid.


sb_update_conversation_department()

Update the department of a conversation and optionally send an email to all the agents in the new department.


Arguments

conversation_id
The ID of the conversation to update.
department
The ID of a department. You can get the IDs from Settings > Miscellaneous > Departments. No department ID validation is performed, so double-check the department ID to be sure it exists.
message
A message to send to the agents. If set, an email with the message will be sent to all the agents to notify the department change.

Response

                                true
                            

sb_set_rating()

Assign a rating to a conversation and optionally update a message of the conversation.


Arguments

settings
Enter the following array: [ "settings" => [ "conversation_id" => "ID", "rating" => "RATING" ] ]. Replace ID with the ID of the conversation to rate, replace rating with 1 for a positive rating, with 0 for a negative rating.
payload
The message payload in JSON format.
message_id
The ID of the message to update.
message
The content of the message.
user_id
The user ID of the conversation linked to the message.

Response

                                true
                            

sb_get_rating()

Get the ratings of the conversations assigned to an agent.


Arguments

user_id
The ID of the agent.

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.


sb_get_new_messages()

Returns the messages of a conversation created after the given date/ID.


Arguments

user_id
The ID of the user of the conversation.
conversation_id
The ID of the conversation.
datetime
Date and time in the following format: YYYY-MM-DD HH:MM:SS. Ex. 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.
last_id
ID of the last message, use this parameter to exclude all messages with a lower ID.

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://brainyassistant.com/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://brainyassistant.com/user.svg",
                                        "user_type": "lead"
                                    },
                                    ...
                                ]
                            

sb_send_message()

Add a new message to an existing conversation.


Arguments

sender_id
The ID of the user who sends the message.
conversation_id
The ID of the conversation.
message
The content of the message.
attachments
Array of attachments. 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
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 of additional information. You can insert any value. Array syntax: { "key": value, "key": value, ... }. Use this attribute to set an event, available events: delete-message, open-chat.
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

                                {
                                    "status": "success",
                                    "message-id": 123456,
                                    "queue": false,
                                    "notifications": ["sms", "email"]
                                }
                            

Other possible responses: invalid-status-code, SQL error message. The notifications response include the notifications sent to the user or agents.


sb_direct_message()

Sends a direct chat message, email, or text message to a single user, or several users. No email and text message notifications are sent for direct chat message. You need to send the notifications manually via sb_email() and sb_send_sms().


Arguments

user_ids
Array, or comma-separated string of user IDs to send the message to. Set it to all to send the message to all users.
message
The message.
subject
The email subject. Only required for emails.

Response

                                true
                            

sb_messaging_platforms_send_message()

Sends a message to the messaging platform linked to the conversation.


Arguments

message
The message.
conversation_id
The conversation ID.
message_id
The ID of the Brainy Assistant message. Use this argument to avoid duplicated messages.

Response

                                true
                            

sb_send_slack_message()

Sends a message to Slack. The Slack App is required and Slack must be active in the settings area.


Arguments

user_id
The ID of the user linked to the message.
full_name
The name of the sender, it will appear in Slack on the left of the message. It should be an agent's name if the message is from an agent, otherwise the user's name.
profile_image
The URL of the profile image of the sender, it will appear in Slack on the left of the message. It should be an agent's profile image if the message is from an agent, otherwise the user's profile image. Supported formats: PNG and JPG. Default:
message
The string containing the message.
attachments
Array of attachments. 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
Conversation ID. Default: false.
channel
The Slack channel linked to the message. For performance reasons always include the channel. You will get the channel after the first call of this function, from the response (example: C011JFFGSKY). Default: false.

Response

                                ["success", "C011JFFGSKY"]
                            

Other possible responses: slack-not-active, SQL, or cURL error message.


sb_update_message()

Update an existing message.


Arguments

message_id
The ID of the message.
message
The content of the message.
attachments
Array of attachments. 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 of additional information. You can insert any value. Array syntax: { "key": value, "key": value, ... }.

Response

                                true
                            

sb_delete_message()

Delete an existing message.


Arguments

message_id
The ID of the message to delete.

Response

                                true
                            

sb_close_message()

Sends the close message to a user conversation. The close message' contents can be set in the Settings > Chat > Close message area.


Arguments

conversation_id
The ID of the conversation to send the message to.
bot_id
The ID of the sender user. Usually the bot ID. You can get the bot ID with the function sb_get_bot_id();

Response

                                {
                                    "status": "success",
                                    "message-id": 123456
                                }
                            

sb_text_formatting_to_html()

Convert the text formatting of chat messages to the equivalent HTML codes and returns the message.


Arguments

message
The text message.

Response

                                Lorem ipsum dolor <b>sit amet</b>, <i>consectetur adipiscing elit</i>, <code>sed</code> do eiusmod tempor incididunt. 
                            

sb_clear_text_formatting()

Remove the text formatting from a chat messages.


Arguments

message
The text message.

Response

                                Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt. 
                            

sb_conversation_security_error()

Verify if the active user is authorized to update the conversation. Agents and admins can always update all conversations, users can only update their own conversations.


Arguments

conversation_id
The conversation ID.

Response

Returns true if the active user is not authorized, otherwise, returns false.


sb_set_agent_active_conversation()

Communicate that an agent is replying to a conversation. The conversation is marked as busy for 2 hours if this function is not executed again by the same agent for another conversation.


Arguments

conversation_id
The conversation ID.
agent_id
The agent ID. Default: active user ID.

sb_is_active_conversation_busy()

Checks if an agent is replying to a conversation. This function checks if the function sb_set_agent_active_conversation() has been executed for the given conversation by another agent within 2 hours.


Arguments

agent_id
The agent ID.
skip
Set it to the active user ID to exclude the active agent from the check. Default: -1.

Response

Returns true if an agent is replying to the conversation.


sb_sb_get_agents_in_conversation()

Returns an array with all the agents with at least one message in the conversation.


Arguments

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://brainyassistant.com/user.svg",
                                            "conversation_id": 1546
                                        },
                                        {
                                            "id": 6413,
                                            "first_name": "Steven",
                                            "last_name": "Travolta",
                                            "profile_image": "https://brainyassistant.com/user.svg",
                                            "conversation_id": 1546
                                        }, 
                                        ...
                                    ],
                                    ...
                                }
                            

PHP API

Database

Database

Functions to read data from the database and to save data in it.


sb_db_get()

Returns the data of a SQL query.


Arguments

query
The SQL query.
single
Set it to false if the query should returns multiple results. Default: true.

Response

The result of the query as a single value or as an array of values. Return SBError if the query is invalid.


sb_db_query()

Execute a SQL query to update the data in the database.


Arguments

query
The SQL query.
return
Set it to true if the query should returns a value. Default: false.

Response

Return true, the returns value, or SBError if the query is invalid.


sb_db_escape()

Escapes special characters in a string for use it in an SQL query. Use this function to escape every variable used in a SQL query containing strings without a known value.


Arguments

value
The string to escape.

Response

Returns the escaped string.


sb_db_json_enconde()

Convert an array to JSON and escape the values for use them in an SQL query. Use this function to convert every variable containing arrays that is used in a SQL query.


Arguments

array
The array to convert and escape.

Response

Returns the converted array.


sb_db_check_connection()

Checks if the database connection is valid or check if the details provided are valid. All arguments are optional. If an argument is not provided will be used the one provided during the installation.


Arguments

name
The database name.
user
The database username.
password
The database password.
host
The database host.
name
The database port.

Response

Return true if the connection is valid, otherwise, returns the connection error message.


PHP API

Language and Translations

Language and Translations

Functions to translate strings in other languages and to manage the translations.


sb_()

Translate a string to the active user language. Use the function sb_e($string) to translate and echo the string.


Arguments

string
The string to translate.

Response

Returns the translated string if available, otherwise, returns the original string.


sb_get_translations()

Returns the translations of the back-end and the front-end, for all the available languages.


Response

                                {
                                    "ar": {
                                        "name": "Arabic",
                                        "front": {
                                            "Activities": "أنشطة",
                                            "All": "الكل",
                                            ...
                                        },
                                        "admin": {
                                            "A conversation was started by": "",
                                            "Activate": "",
                                            ...
                                        },
                                        "admin/js": {
                                            "Add new user": "",
                                            "Add translation": "",
                                            ...
                                        },
                                        "admin/settings": {
                                            "Active for agents": "",
                                            "Active for users": "",
                                            ...
                                        }
                                    },
                                    "da": {
                                        "name": "Danish",
                                        "front": {
                                            "Activities": "Aktiviteter",
                                            "All": "Alle",
                                            ...
                                        },
                                        ...
                                    },
                                    ...
                                }
                            

sb_get_translation()

Returns the translations of the back-end and the front-end of a single language.


Response

                                {
                                    "name": "Arabic",
                                    "front": {
                                        "Activities": "أنشطة",
                                        "All": "الكل",
                                        ...
                                    },
                                    "admin": {
                                        "A conversation was started by": "",
                                        "Activate": "",
                                        ...
                                    },
                                    "admin/js": {
                                        "Add new user": "",
                                        "Add translation": "",
                                        ...
                                    },
                                    "admin/settings": {
                                        "Active for agents": "",
                                        "Active for users": "",
                                        ...
                                    }
                                }
                            

sb_save_translations()

Save the translations and overwrite the translations files. Warning! If the given translations array is corrupted you could corrupt the translations files. Make a backup of the translations folder ( \resources\languages\) first. Each time a translation is saved a backup is created automatically in the uploads folder.


Arguments

translations
The translations array with all the translations. Use the function sb_get_translations() to get it.

Response

true

sb_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. Default: false.

Response

The language code. Examples: es, it.


sb_get_admin_language()

Returns the language code of the admin area relative to the active user.


Arguments

user_id
The ID of the agent or admin from whom you want to get the language. Default: false.

Response

The language code. Examples: es, it.


PHP API

Dialogflow

Dialogflow

Dialogflow App functions to manage the chatbot and more. The Dialogflow App is required to use this set of APIs.


sb_dialogflow_message()

Sends a message to Dialogflow and add the Dialogflow response to an existing conversation as a new message.


Arguments

conversation_id
The ID of the conversation.
message
The content of the message.
token
Dialogflow Session Token(it's not the Refresh Token). Pass it if you have it, otherwise it will be generated. For performance reasons always include this token. You will get the token after the first call of this function, from the response. Default: false.
language
The Dialogflow agent language code. Default: main agant language code.
attachments
Array of attachments. Array syntax: [["name", "link"], ["name", "link"], ...]. Replace name with the name of the attachment and link with the full URL of the attachment. Dialogflow can read this array. Default: [].
event
Trigger a Dialogflow event.
parameters
Array of optional information. Array syntax: { "name": "value", "name": "value", ...}.
project_id
Set it to change the default Dialogflow agent.

Response

                                {
                                    "token": "ya29.a0AfH6SMB5Y04TwKvxeah5pCEtcupfncTOLMlewxlnUAhH5H4HE4SVIeOPWSfxRVfHNcJIoR-IvRTtrEe4P9VXHa",
                                    "messages": [
                                        {
                                            "message": "Hi! How are you doing?",
                                            "attachments": []
                                        }
                                    ],
                                    "response": {
                                        "responseId": "1a5e30d0-d6d4-4f0c-83e3-2fb9e31c2a5e-e15c53b8",
                                        "queryResult": {
                                            "queryText": "Hello",
                                            "action": "input.welcome",
                                            "parameters": [],
                                            "allRequiredParamsPresent": true,
                                            "fulfillmentText": "Hi! How are you doing?",
                                            "fulfillmentMessages": [
                                                {
                                                    "platform": "ACTIONS_ON_GOOGLE",
                                                    "simpleResponses": {"simpleResponses": [ { "textToSpeech": "Example"} ]}
                                                },
                                                {
                                                    "text": { "text": [ "Hi! How are you doing?" ]  }
                                                }
                                            ],
                                            "intent": {
                                                "name": "projects/api-project-655517752147/agent/intents/fe275c2e-f39d-4db3-92c2-e55582ce38fb",
                                                "displayName": "Default Welcome Intent"
                                            },
                                            "intentDetectionConfidence": 1,
                                            "languageCode": "en"
                                        },
                                        "alternativeQueryResults": [
                                            {
                                                "queryText": "Hello",
                                                "languageCode": "en"
                                            }
                                        ]
                                    }
                                }
                            

Other possible responses: dialogflow-not-active, SQL, or cURL error message.


sb_dialogflow_curl()

Sends data to Dialogflow. Use this function to submit the queries to Dialogflow.


Arguments

url_part
The Dialogflow API partial URL. Examples: /agent/entityTypes, /agent/intents:batchUpdate.
query
The Dialogflow query in JSON format or as array.
language
The Dialogflow agent language code. Default: main agant language code.
type
The call type. Supported values: POST, GET, PATCH. Default: POST.
token
The Dialogflow Session Token(it's not the Refresh Token). Pass it if you have it, otherwise it will be generated. Default: false.

Response

Returns the Dialogflow response in associative array format. More details at https://cloud.google.com/dialogflow/es/docs/reference/rest/v2-overview


sb_dialogflow_get_token()

Generate a new Dialogflow Token and returns it. The token is valid for 1 hour.


Response

                                ya27.a1AfH6SMDu9dn0TfRbNVAIEsSoeJPD1_jr1JpfL15...
                            

sb_dialogflow_get_agent()

Returns the details of the Dialogflow agent.


Response

                                {
                                    "parent": "projects/woocommerce-abcde",
                                    "displayName": "ABCDE",
                                    "defaultLanguageCode": "en",
                                    "timeZone": "Europe/Madrid",
                                    "enableLogging": true,
                                    "matchMode": "MATCH_MODE_HYBRID" ,
                                    "classificationThreshold": 0.6,
                                    "apiVersion": "API_VERSION_V2",
                                    "tier": "TIER_STANDARD"
                                }
                            

sb_dialogflow_set_active_context()

Activate a Dialogflow context in the active user session.


Arguments

context_name
The context name.
parameters
Array of Dialogflow parameters linked to the context. Example: ['woocommerce-products' => 'Running Shoes']. The array can be also a string in JSON format.
life_span
The context lifespan. Default: 5.
token
The Dialogflow refresh token.
user_id
The ID of the user linked to the context. Default: active user.
language
The agent language. Default: active user language.

Response

                                {
                                   "responseId": "4f6912db-71ac-41e1-b006-088b7647cb59-fddac234",
                                   "queryResult":{
                                      "queryText": "sb-trigger-context",
                                      "parameters":{
                                         "any": "sb-trigger-context"
                                      },
                                      "allRequiredParamsPresent":true,
                                      "fulfillmentMessages":[
                                         {
                                            "text":{
                                               "text":[
                                                  ""
                                               ]
                                            }
                                         }
                                      ],
                                      "outputContexts":[
                                         {
                                            "name": "projects/abcde/agent/sessions/244/contexts/abcde",
                                            "lifespanCount":1,
                                            "parameters":{
                                               "woocommerce-products": "",
                                               "any": "sb-trigger-context",
                                               "any.original": "sb-trigger-context"
                                            }
                                         }
                                      ],
                                      "intent":{
                                         "name": "projects/abcd/agent/intents/abcde",
                                         "displayName": "woocommerce-waiting-list"
                                      },
                                      "intentDetectionConfidence":0.6,
                                      "languageCode": "en"
                                   }
                                }
                            

sb_dialogflow_create_intent()

Create a new Dialogflow Intent. The Intent will be linked to the Dialogflow agent synchronized in the admin area.


Arguments

expressions
Array with the training phrases. Array syntax: ["", "", ...].
response
String containing the response of the bot when the user input matches a user expression.
agent_language
The language code of the intent. Default: main agent language. For the language codes list visit cloud.google.com/dialogflow/docs/reference/language.

sb_dialogflow_batch_intents()

Create multiple Dialogflow Intents and allow a deeper customization than the sb_dialogflow_create_intent() function.


Arguments

intents
Array of Intents. Each Intent must be a SBDialogflowIntent object.
language
The Dialogflow agent language code. Default: main agant language code.

Response

                                {
                                   "name": "projects/woocommerce-app-rojq/operations/bg-f0adhdc5-a1a1-472b-a06c-15559a12cfc7",
                                   "done":true,
                                   "response":{
                                      "@type": "type.googleapis.com/google.cloud.dialogflow.v2.BatchUpdateIntentsResponse",
                                      "intents":[
                                         {
                                            "name": "projects/abcde/agent/intents/abcde",
                                            "displayName": "Cart details",
                                            "priority":500000,
                                            "outputContexts":[
                                               {
                                                  "name": "projects/abcde/agent/sessions/-/contexts/abcde",
                                                  "lifespanCount":5
                                               }
                                            ],
                                            "messages":[
                                               {
                                                  "text":{
                                                     "text":[
                                                        "Hi there!"
                                                     ]
                                                  }
                                               }
                                            ]
                                         },
                                         ...
                                      ]
                                   }
                                }
                            

sb_dialogflow_batch_intents_delete()

Delete multiple Intents at once.


Arguments

intents
Array of Intents. Each Intent must be a SBDialogflowIntent object. You can get the existing Intents with the function sb_dialogflow_curl('/agent/intents?pageSize=1000', '', '', 'GET').

sb_dialogflow_create_entity()

Create a new Dialogflow Entity.


Arguments

entity_name
The Entity unique name.
values
SBDialogflowEntity object or array of Entity values. Single value syntax: ['value' => '', 'synonyms' => ['', '', ...]].
language
The Dialogflow agent language code. Default: main agant language code.

Response

Return true on success, otherwise returns the Dialogflow error response.


sb_dialogflow_update_entity()

Update an existing Dialogflow Entity.


Arguments

entity_id
The Entity ID. You can get this value with the function sb_dialogflow_get_entity().
values
SBDialogflowEntity object or array of Entity values. Single value syntax: ['value' => '', 'synonyms' => ['', '', ...]].
language
The Dialogflow agent language code. Default: main agant language code.

Response

Return true on success, otherwise returns the Dialogflow error response.


sb_dialogflow_get_entity()

Returns a Dialogflow Entity, or all Entities of the agent.


Arguments

entity_id
The ID of the Entity. Leave empty or insert all to get all Entities. Default: all.
language
The Dialogflow agent language code. Default: main agant language code.

Response

                                [
                                   {
                                      "name": "projects/small-talk-43da7/agent/entityTypes/t5td1425-2k13-16cc-a7bb-f119b8d94112a",
                                      "displayName": "woocommerce-products",
                                      "kind": "KIND_MAP",
                                      "autoExpansionMode": "AUTO_EXPANSION_MODE_DEFAULT",
                                      "entities":[
                                         {
                                            "value": "Abstract Print Cotton Blouse",
                                            "synonyms":[
                                               "Abstract Print Cotton Blouse"
                                            ]
                                         },
                                         {
                                            "value": "Cashmere Carpenter Beanie",
                                            "synonyms":[
                                               "Cashmere Carpenter Beanie"
                                            ]
                                         },
                                         ...
                                      ],
                                      "enableFuzzyExtraction":true
                                   }
                                ]
                            

sb_open_ai_curl()

Call the OpenAI API (ChatGPT) and return the response.


Arguments

url_part
The URL part of the API. For example, if you want to call https://api.openai.com/v1/completions, enter only completions.
post_fields
The parameters of the API.
type
The HTTP call type. Allowed values: GET, POST, UPLOAD.

Response

Returns the openAI response. More details at https://beta.openai.com/docs/api-reference/.


PHP API

WordPress

WordPress

WordPress functions.


sb_wp_get_user()

Returns the details of a WordPress user.


Arguments

user_id
The WordPress user ID.

Response

                                {
                                   "id": 123,
                                   "first_name": "Don",
                                   "last_name": "John",
                                   "email": "email@example.com",
                                   "password": "$P$BcCpYeU21wYnXKW2LpJj/F9xRdSmLM/"
                                }
                            

Returns false if no user was found.


sb_wp_get_active_user()

Get the currently active WordPress user and register it as a Brainy Assistant user. If a Brainy Assistant user is currently active, update it with the WordPress details. After the registration the user is logged-in. Returns the login details and encrypted data of the Brainy Assistant user.


Arguments

user_id
The currently active WordPress user ID.

Response

                                 [
                                    {
                                        "id": "913",
                                        "profile_image": "https://brainyassistant.com/user.svg",
                                        "first_name": "User",
                                        "last_name": "#29902",
                                        "email": null,
                                        "user_type": "visitor",
                                        "token": "9b25351047ee758aa97ee4868d130cc1ceb8decf"
                                    },
                                    "YXNkWGNSeTdtRTdDYVkxVG8wckN4YWF6V2s0Tk1mczBSVHdQbHBpOWdmejVUTTdOUUxEUENhdUVoYmROWn..."
                                ]
                            

sb_wp_synch()

Syncronize the WordPress users with the Brainy Assistant users. If Ultimate Membership Pro App is installed, the syncronization imports also the additional users details.


Response

                                true
                            

sb_wp_get_user_id()

Returns the user ID of the WordPress user with the given email.


Arguments

email
The user email.

Response

                                1234
                            

Returns false if no user was found.


sb_wp_post()

Save a new WordPress post (page, post, ...). This function is equivalent to wp_insert_post().


Arguments

post_title
The post title.
post_content
The post content.
post_type
The post type. Ex.: page, post.

Response

Returns the ID of new post.


sb_wp_update_option()

Create or update a WordPress option. This function is equivalent to update_option().


Arguments

name
The option name.
value
The option value.

Response

Returns the ID of new option.


sb_wp_get_option()

Returns the value of a WordPress option. This function is equivalent to get_option().


Arguments

name
The option name.

Response

Returns the option value, or false if no option with given name was found.


sb_wp_get_image()

Returns the URL of the image with the given ID. This function is equivalent to wp_get_attachment_image_src().


Arguments

id
The WordPress image ID.

Response

                                https://example.com/image.jpg
                            

Returns an empty string if no image with the given ID was found.


sb_wp_site_url()

Returns the website URL.


Response

                                https://www.example.com
                            

sb_wp_language_settings()

Returns the languages settings of WordPress.


Arguments

plugin
The multilingual plugin name. Default: the plugin set at Settings > WordPress > Multilingual plugin.

Response

                                {
                                    "default": "en",
                                    "languages": [
                                        "en",
                                        "de",
                                        "it"
                                    ],
                                    "post-types": [
                                        "attachment",
                                        "wp_block",
                                        "product",
                                        "product_variation",
                                        "food",
                                        "post",
                                        "page"
                                    ],
                                    "taxonomies": [
                                        "translation_priority",
                                        "product_cat",
                                        "product_tag",
                                        "product_shipping_class",
                                        "pa_colore-prodotti",
                                        "pa_taglia-prodotti",
                                        "category",
                                        "post_tag"
                                    ],
                                    "link-type": "3",
                                    "plugin": "wpml"
                                }
                            

sb_wp_language_get_page_id()

Returns the translated page ID of the given page ID.


Arguments

id
The page ID.

Response

Returns the translated page ID if the translation is found, otherwise returns the given ID.


PHP API

WooCommerce

WooCommerce

WooCommerce App functions. The WooCommerce App is required to use this set of APIs.


sb_woocommerce_get_customer()

Returns the details of a WooCommerce customer.


Arguments

session_key
The customer session key. You can get this value with the function sb_woocommerce_get_session_key().

Response

                                {
                                   "customer_id": "1",
                                   "user_id":null,
                                   "username": "",
                                   "first_name": "Don",
                                   "last_name": "John",
                                   "email": "email@example.com",
                                   "date_last_active": "2020-08-03 07:21:18",
                                   "date_registered":null,
                                   "country": "UK",
                                   "postcode": "E14HR",
                                   "city": "London",
                                   "state": ""
                                }
                            

sb_woocommerce_get_user_orders()

Returns an array with the orders summary of the user. Use the function sb_woocommerce_get_last_order() to get only the last order of the user.


Arguments

user_id
The user ID.

Response

                                [
                                    {
                                        "id": "602",
                                        "date": "2020-10-19 14:02:35",
                                        "total": "0",
                                        "status": "wc-on-hold",
                                    },
                                    {
                                        "id": "601",
                                        "date": "2020-10-18 14:02:35",
                                        "total": "0",
                                        "status": "wc-processing",
                                    },
                                    ...
                                ]
                            

sb_woocommerce_get_order()

Returns the details of an order.


Arguments

order_id
The order ID.

Response

                                {
                                    "id": "601",
                                    "date": "2020-10-19 14:02:10",
                                    "total": "19",
                                    "status": "wc-on-hold",
                                    "products": [
                                        {
                                            "name": "Sony Play Station 5",
                                            "id": "53",
                                            "quantity": "1",
                                            "price": "199"
                                        }
                                    ],
                                    "billing_address": "Don John\\n501 Baker Street\\nEW578H London, UK",
                                    "shipping_address": "",
                                    "currency_symbol": "€"
                                }
                            

sb_woocommerce_get_product()

Returns the details of a product.


Arguments

product_id
The product ID.

Response

                                {
                                    "id": "53",
                                    "name": "Sony Play Station 5",
                                    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elite...",
                                    "price": "19",
                                    "image": "https://example.com/image.jpg",
                                    "rating": "",
                                    "url": "https://example.com/?p=53"
                                }
                            

sb_woocommerce_get_products()

Returns the products matching the given query if any, otherwise returns all products.


Arguments

filters
Array of filters. Syntax: [ "filter" => "value", "filter" => "value", ... ]. Use filters to only get products that match specific criteria. Available filters:
  • taxonomy
    Taxonomy ID or name. Categories and tags are taxonomies.
  • attribute
    Product attribute term name. Example: color, size.
  • date
    Product publication date. If the value is a string, returns only the products older than the given date. If the value is an array, returns the products between the given dates. Array syntax: [ "startDate" => "", "endDate" => "" ]. Multiple date formats are supported. Example: 2020-12-30 06:35:59.
  • max-price
    Product max price. Returns only the products with a price lower than the give one.
  • min-price
    Product min price. Returns only the products with a price larger than the give one.
  • discounted
    Products in promotion. Set it to true to returns only the products in promotion.
pagination
Limit the number of results to 100. Set it to 0 to get the products from 1 to 100, to 1 to get the products from 101 to 200...
language
The products language code. Default: false.

Response

                                [
                                    {
                                        "id": "53",
                                        "name": "Sony Play Station 5",
                                        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elite...",
                                        "date": "2020-08-03 07:06:25",
                                        "price": "19",
                                        "image": "https://example.com/image.jpg",
                                        "rating": "",
                                        "url": "https://example.com?p=53"
                                    },
                                    {
                                        "id": "54",
                                        "name": "Xbox Series X",
                                        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elite...",
                                        "date": "2020-08-03 07:08:19",
                                        "price": "59",
                                        "image": "https://example.com/image.jpg",
                                        "rating": "",
                                        "url": "https://example.com?p=54"
                                    },
                                    ...
                                ]
                            

sb_woocommerce_search_products()

Returns the products matching the search.


Arguments

search
The search string.

Response

                                [
                                    {
                                        "id": "53",
                                        "name": "Sony Play Station 5",
                                        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elite...",
                                        "date": "2020-08-03 07:06:25",
                                        "price": "19",
                                        "image": "https://example.com/image.jpg",
                                        "rating": "",
                                        "url": "https://example.com?p=53"
                                    },
                                    {
                                        "id": "54",
                                        "name": "Xbox Series X",
                                        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elite...",
                                        "date": "2020-08-03 07:08:19",
                                        "price": "59",
                                        "image": "https://example.com/image.jpg",
                                        "rating": "",
                                        "url": "https://example.com?p=54"
                                    },
                                    ...
                                ]
                            

sb_woocommerce_get_taxonomies()

Returns the WooCommerce product categories or tags.


Arguments

type
Insert category or tag.
language
The language code of the taxonomies. Default: false.

Response

                                [
                                    {
                                        "id": "33",
                                        "name": "Clothes",
                                        "slug": "clothes"
                                    },
                                    {
                                        "id": "34",
                                        "name": "Accessories",
                                        "slug": "accessories"
                                    },
                                    ...
                                ]
                            

sb_woocommerce_get_attributes()

Returns the WooCommerce product attributes and attribute terms.


Arguments

type
Set it to terms to returns only the terms name of all attributes, and to attribute to returns only the attributes name. Default: all.
language
The language code of the attributes. Default: false.

Response


All
                                {
                                    "colors": {
                                        "id": "1",
                                        "name": "Color",
                                        "slug": "pa_color",
                                        "terms": {
                                            "red": "Red",
                                            "yellow": "Yellow",
                                            "green": "Green",
                                            ...
                                        }
                                    },
                                    ...
                                }
                            
Terms
                                [
                                    {
                                        "name": "Red"
                                    },
                                    {
                                        "name": "Yellow"
                                    },
                                    {
                                        "name": "Small"
                                    },
                                    {
                                        "name": "Medium"
                                    },
                                    {
                                        "name": "Large"
                                    },
                                    ...
                                ]
                            
Attributes
                                [
                                    {
                                        "id": "1",
                                        "name": "Color",
                                        "slug": "pa_color"
                                    },
                                    {
                                        "id": "2",
                                        "name": "Size",
                                        "slug": "pa_size"
                                    },
                                    ...
                                ]
                            

sb_woocommerce_get_product_id_by_name()

Search a product by name and returns its ID.


Arguments

name
The product name.

Response

Returns the product ID, or false if no products with the given name are found.


sb_woocommerce_get_product_images()

Returns an array with the images of a product.


Arguments

product_id
The product ID.

Response

                                [
                                    "https://example.com/image.jpg",
                                    "https://example.com/image.jpg",
                                    ...
                                ]
                            

sb_woocommerce_get_product_taxonomies()

Returns the categories and tags of a product.


Arguments

product_id
The product ID.

Response

                                [
                                    {
                                        "term_id": "34",
                                        "name": "Red",
                                        "slug": "red",
                                        "term_group": "0",
                                        "taxonomy": "product_cat"
                                    },
                                    {
                                        "term_id": "35",
                                        "name": "Summer Edition",
                                        "slug": "summer-edition",
                                        "term_group": "0",
                                        "taxonomy": "product_tag"
                                    },
                                    ...
                                ]
                            

sb_woocommerce_get_attribute_by_term()

Returns the attribute of an attribute term.


Arguments

term_name
The term name.

Response

                                {
                                    "id": "1",
                                    "name": "Color",
                                    "slug": "pa_color"
                                }
                            

sb_woocommerce_get_attribute_by_name()

Search an attribute by its name and returns it.


Arguments

name
The attribute name.

Response

                                {
                                    "id": "1",
                                    "name": "Color",
                                    "slug": "pa_color"
                                }
                            

sb_woocommerce_is_in_stock()

Check if a product is in stock.


Arguments

product_id
The product ID.

Response

Return true if the product is available, otherwise return false.


sb_woocommerce_coupon()

Generate a coupon and returns the coupon code.


Arguments

discount
Discount percentage. Insert a value from 1 to 100.
expiration
Coupon expiration. Example: 3 days, 1 minutes, 60 seconds.
product_id
String of IDs separated by commas. Example: 11,53,63. If setted the coupon is valid only for the products with the given IDs.
user_id
If setted the coupon is valid only for the user with the given ID.

Response

                                [ "fxsocl3490oq", "50" ]
                            

[ coupon code, discount value ]


sb_woocommerce_coupon_check()

Check if there are coupons linked to the given user.


Arguments

user_id
The user ID.

Response

Returns true if there are coupons linked to the user, otherwise returns false.


sb_woocommerce_coupon_delete_expired()

Delete all expired coupons. This function runs automatically every hour via cron jobs.


Response

                                true
                            

sb_woocommerce_rating()

Calculate and returns the average rating.


Arguments

rating
Array of ratings. Get this value from the rating value of a product.

Response

                                4.56
                            

sb_woocommerce_get_url()

Returns a WooCommerce URL.


Arguments

type
The URL type to get. Accepted values: tag, category, cart, shop, , checkout.
name
The name of the caetgory or link.
language
The language of the page of the URL. Default: false.

Response

Returns the URL if found, otherwise returns an empty string.


sb_woocommerce_get_session()

Returns the session variable of a user. The session variable contains the user cart details and more.


Arguments

session_key
The session key of a user. Get it with the function sb_woocommerce_get_session_key(). Default: active user session key.

Response

                                {
                                    "cart": {
                                        "d82c8d1619ah8176d665453cfb2e66f0": {
                                            "key": "d82c8d1619ah8176d665453cfb2e66f0",
                                            "product_id": 53,
                                            "variation_id": 0,
                                            "variation": [],
                                            "quantity": 3,
                                            "data_hash": "b5c1d6ca8bae6d4896jf1807cdf713f0",
                                            "line_tax_data": {
                                                "subtotal": [],
                                                "total": []
                                            },
                                            "line_subtotal": 57,
                                            "line_subtotal_tax": 0,
                                            "line_total": 57,
                                            "line_tax": 0
                                        }
                                    },
                                    "cart_totals": {
                                        "subtotal": "57.00",
                                        "subtotal_tax": 0,
                                        "shipping_total": "0.00",
                                        "shipping_tax": 0,
                                        "shipping_taxes": [],
                                        "discount_total": 0,
                                        "discount_tax": 0,
                                        "cart_contents_total": "57.00",
                                        "cart_contents_tax": 0,
                                        "cart_contents_taxes": [],
                                        "fee_total": "0.00",
                                        "fee_tax": 0,
                                        "fee_taxes": [],
                                        "total": "57.00",
                                        "total_tax": 0
                                    },
                                    "applied_coupons": "a:0:{}",
                                    "coupon_discount_totals": "a:0:{}",
                                    "coupon_discount_tax_totals": "a:0:{}",
                                    "removed_cart_contents": "a:0:{}",
                                    "customer": {
                                        "id": "1",
                                        "date_modified": "2020-08-20T09:33:03+00:00",
                                        "postcode": "",
                                        "city": "",
                                        "address_1": "",
                                        "address": "",
                                        "address_2": "",
                                        "state": "",
                                        "country": "",
                                        "shipping_postcode": "",
                                        "shipping_city": "",
                                        "shipping_address_1": "",
                                        "shipping_address": "",
                                        "shipping_address_2": "",
                                        "shipping_state": "",
                                        "shipping_country": "",
                                        "is_vat_exempt": "",
                                        "calculated_shipping": "",
                                        "first_name": "",
                                        "last_name": "",
                                        "company": "",
                                        "phone": "",
                                        "email": "",
                                        "shipping_first_name": "",
                                        "shipping_last_name": "",
                                        "shipping_company": ""
                                    }
                                }
                            

sb_woocommerce_get_session_key()

Returns the session key of a user.


Arguments

user_id
The user ID. Default: active user ID.

Response

Returns the session key if found, otherwise returns false.


sb_woocommerce_payment_methods()

Returns the available payment methods of the shop.


Response

                                [
                                    "Direct bank transfer",
                                    "Check payments",
                                    "Cash on delivery",
                                    "Alipay",
                                    "Multibanco",
                                    "Credit Card (Stripe)"
                                ]
                            

sb_woocommerce_shipping_locations()

Returns the shop shipping locations, or check if the shop ships to a specific location.


Arguments

country_code
A country code. If provided checks if the shop ships to the country of the given given code. Default: false.

Response

                                [
                                    "Australia, Italy, United States, ...",
                                    [
                                        [
                                            "Australia",
                                            "AU"
                                        ],
                                        [
                                            "Italy",
                                            "IT"
                                        ],
                                        [
                                            "United States",
                                            "US"
                                        ],
                                        ...
                                    ],
                                    false
                                ]
                            

The last array value is true if the shop does not ship to the returned countries.


PHP API

Pusher

More functions

List of functions for Pusher. More details at pusher.com.


sb_push_notification()

Sends a Push notification to an agent, user, or all agents.


Arguments

title
The title of the notification.
message
The message text.
icon
The icon of the notification. Default: Brainy Assistant icon or notifications icon.
interest
The following values are accepted:
  • Agent or user ID
  • Array of agents or users IDs (ex. [1, 2, 3])
  • The string agents to send the notification to all agents without a department assigned.
  • The string all-agents to send the notification to all agents.
  • The string department-ID to send the notification to all agents assigned to the given department. Replace ID with the department ID.
conversation_id
The ID of the conversation to open when the user clicks the notification.
user_id
The ID of user who sent the message.
attachments
Message attachments to show the image preview. Syntax: [["name", "url"], ...].

Response

                                {
                                    "publishId": "pubid-781799f5-6el4-4789-bc60-ee293543781"
                                }
                            

Return false it the Push notifications are disabled in the settings area.


sb_pusher_trigger()

Trigger an avent on a Pusher channel.


Arguments

channel
The channel name.
event
The event name.
data
Array of values. Syntax: [ "name" => "value" ].

Response

                                true
                            

sb_pusher_get_online_users()

Returns the array of IDs of online users and agents subscribed to the presence channel.


Response

                                [
                                    {
                                        "id": "1538"
                                    },
                                    {
                                        "id": "1758"
                                    },  
                                    ...
                                ]
                            

sb_pusher_agents_online()

Check if there is at least one agent online by checking the presence channel.


Response

true if online, false if offline.


sb_pusher_active()

Check if Pusher is active in Settings > Miscellneous > Pusher.


Response

true if active, false otherwise.


sb_pusher_init()

Initialize the Pusher PHP SDK.


PHP API

More functions

More functions

Various functions that perform different tasks.


sb_email()

Sends an email to an existing user using the email templates, and settings, of the Settings > Notifications area. The email is translated automatically.


Arguments

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: active user ID.

Response

                                true
                            

sb_email_send()

Sends a generic email to an email address. The sender email and name are the ones set in Settings > Notifications > Email settings.


Arguments

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
                            

sb_email_piping()

Runs the email piping synchronization with Brainy Assistant and converts emails to chat messages.


Arguments

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
                            

sb_send_sms()

Sends a text message to a user or agent. If the template argument is true, the message is translated automatically.


Arguments

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"
                                }
                            

sb_send_agents_notifications()

Sends all the agent notifications: email notification, push notification, and SMS notification.


Arguments

message
The message text.
bottom_message
Additional message to append at the end of the email notification.
conversation_id
The ID of the conversation linked to the message. If this value is not set the notifications are sent to all agents.
attachments
Array of attachments. 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: false.
user
User of the conversation as array of user details.
extra
Array of values. Enter the value force: true to force the notifications also if the agent is online. Enter the value email: [email_content] to send a different message only for the email notification.

Response

                                true
                            

sb_get_setting()

Returns a setting of the settings area.


Arguments

setting
The setting ID. You can get the IDs of all the settings from the file resources\json\settings.json.

Response

Returns the value of the setting.


sb_get_settings()

Returns an array with all the settings.


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"
                                    ],
                                    ...
                                }
                            

sb_save_settings()

Save the chat settings. This function overwrite all settings with the given ones.


Arguments

settings
Array of settings. You can get the array of the current settings with the function sb_get_settings().
external_settings
Array of additional settings. Each value of the array is saved in a new row of the table sb_settings of the database. Default [].
external_settings_translations
Array of translations of the external settings. Each language of the array is saved in a new row of the table sb_settings of the database. Array syntax: [ "es" => [], "it" => [], ...] Default [].

Response

                                true
                            

sb_get_multilingual_setting()

Returns the translated value a multilingual and multi values setting of the settings area.


Arguments

name
The ID of the setting. Set it to emails to get the emails settings.
sub_name
The ID of the sub setting. Ex. email-agent. Get the list of all IDs from the file resources/json/settings.json.
language
The language code. If there are no translations for the given language code, or if it's set to false or en, the default language is returned instead. Default: false.

Response

                                true
                            

sb_is_error()

Check if a variable is of type SBError. Use the method $error->code() to get the error code, the method $result->function_name() to get the function name that generated the error, the method $result->message() to get the error message.


Arguments

object
The variable to check.

Response

Return true if the variable is of type SBError, otherwise, return false.


sb_is_validation_error()

Check if a variable is of type SBValidationError. Use the method $error->code() to get the error code.


Arguments

object
The variable to check.

Response

Return true if the variable is of type SBValidationError, otherwise, return false.


sb_isset()

Check if an array key exists and returns its value only if it exists and if it isn't an empty string.


Arguments

array
The array in which to look for the key.
key
The key to search.
default
The value to returns if the key is not found or if it's empty. Default: false.

Response

Returns the value of the key or the default value.


sb_archive_slack_channels()

Archive all the Slack channels. If you have a lot of channels, this operation may take a long time to complete and you could need to execute it again multiple times. Important: All of your slack channels will be archived. The Slack App is required.


Response

                                true
                            

sb_get_articles()

Returns an array with all the articles or a single article.


Arguments

id
The ID of the article. Add multiple IDs separated by commas. To get the article IDs execute this function without any argument. Default: false.
count
The maximum number of returned articles. Default: all.
full
Set it to true to get full-length articles contents. Default: false.
categories
Boolean. Set it to true to get the array of all categories. If true the response is a double array, first item articles, second item categories. 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

                                [
                                    {
                                        "id": "6P2Oq",
                                        "title": "What's new with the API V2?p",
                                        "content": "The API V2 is the new iteration of o ...",
                                        "link": "https://brainyassistant.com"
                                        "categories": ["ols85"]
                                    },
                                    {
                                        "id": "qf7kD"
                                        "title": "Should I move to the new API?",
                                        "content": "Yes. The newest version (V2) of the Actions ...",
                                        "link": "https://brainyassistant.com",
                                        "categories": []
                                    },
                                    ...
                                ]
                            

Single article response

                                {
                                    "id": "6P2Oq",
                                    "title": "What's new with the API V2?p",
                                    "content": "The API V2 is the new iteration of our developer API. The new API integrates...",
                                    "link": "https://brainyassistant.com",
                                    "categories": ["ols85"]
                                }
                            

sb_save_articles()

Save all the articles. This function replaces all the existing articles with the articles of the given array.


Arguments

articles
The array with the articles. Use the function sb_get_articles() to get the articles array. Array syntax:
[["id" => "", "title" => "", "content" => "", "link" => ""] , ["title" => "", "content" => "", "link" => "", "id" => ""], ...]
categories
Array of category IDs. Set it to delete_all to delete all categories.
translations
The array with the articles translations. Use the function sb_get_articles() to get the articles array. Array syntax:
[ "es" => [["id" => "", "title" => "", "content" => "", "link" => ""], ...], "it" => [...], ...]

Response

                                true
                            

sb_search_articles()

Returns the articles matching the search.


Arguments

search
String with the search terms. The search function supports the title and the 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

                                [
                                    {
                                        "id": "6P2Oq",
                                        "title": "What's new with the API V2?p",
                                        "content": "The API V2 is the new iteration of o ...",
                                        "link": "https://brainyassistant.com",
                                        "categories": ["ols85"]
                                    },
                                    {
                                        "id": "qf7kD"
                                        "title": "Should I move to the new API?",
                                        "content": "Yes. The newest version (V2) of the Actions ...",
                                        "link": "https://brainyassistant.com",
                                        "categories": []
                                    },
                                    ...
                                ]
                            

sb_get_articles_categories()

Returns an array with all the articles categories.


Response

                                [
                                    {
                                        "id": "Nv9PG",
                                        "title": "Business"
                                    },
                                    {
                                        "id": "csPVh",
                                        "title": "Travel And Tourism"
                                    },
                                    {
                                        "id": "pl5S7",
                                        "title": "Finance"
                                    },
                                    ...
                                ]
                            

sb_save_articles_categories()

Save or update the articles categories array.


Arguments

categories
Array of categories. Array syntax: [ { "id": "123456", "title": "Category name" }, { "id": "123456", "title": "Category name" }, ...]. Get the existing categories array with the function get_articles_categories().

Response

                                true
                            

sb_article_ratings()

Get the ratings of an article or add a new rating to it.


Arguments

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 function adds the rating, otherwise returns the existing ratings. Default: false.

Response

                                [-1, 1, 1, -1, ...]
                            

Returns true if the rating argument is set.


sb_get_versions()

Returns the installed version of Brainy Assistant and the Apps.


Response

                                {
                                    "sb": "3.0.4",
                                    "dialogflow": "1.0.2",
                                    "slack": "1.0.3"
                                }
                            

sb_update()

Start the update of Brainy Assistant and all the apps. This function forces the update and always overwrite all plugin and apps files.


Response

                                success
                            

sb_wp_synch()

Start the synchronization of the WordPress users and import the new WordPress users into Brainy Assistant. This function is available only in the WordPress version.


Response

                                true
                            

sb_wp_update_option()

Save an option to the wp_options table. This function is equivalent to the WordPress function update_option().


Arguments

name
The option name.
value
The option value.

Response

                                true
                            

sb_app_get_key()

Returns the License Key of a Brainy Assistant App like the Slack App or the Dialogflow App.


Arguments

app_name
Insert one of the following values: slack , dialogflow .

Response

                                9300AB16-014ZEE12-91E199EA-997CEX40
                            

sb_app_activation()

Activate an app, download it, and install it.


Arguments

app_name
Insert one of the following values: slack , dialogflow .
key
The License Key of the App. You can get the key with the function app-get-key.

Response

                                success
                            

sb_csv_users()

Export all the users in a CSV file and returns the URL.


Response

Returns the URL of the CSV file.


sb_transcript()

Export a conversation in a CSV or TXT file and returns the URL.


Arguments

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

Returns the URL of the CSV file.


sb_json_array()

Convert a JSON string to an array.


Arguments

json
The JSON string.
default
The value to returns if the conversion is unsuccessful. Default: [].

Response

Returns a PHP array if the conversion is successful, otherwise, returns the default value.


sb_office_hours()

Check if the current time is within the office hours.


Response

Return true if the current time is within the office hours, otherwise, return false.


sb_encryption()

Encrypt a string or decrypt an encrypted string.


Arguments

string
The string to encrypt or decrypt.
encrypt
Set it to false to decrypt. Default: true.

Response

Returns the encrypted string or the decrypted string.


sb_string_slug()

Convert a string to a slug or a slug to a string. When converting a string to a slug all spaces are converted to - and all chars are in lowercase. When converting a slug to a string all the occurrences of the chat - are converted to spaces and the first chat is in uppercase.


Arguments

string
The string to convert.
action
Insert slug to convert a string to a slug, insert string to convert a slug to a string. Default: "slug".

Response

Returns the slug or the converted string.


sb_curl()

Sends data to a URL to get a JSON response.


Arguments

url
The destination URL that will receive the data.
post_fields
Array with the attributes. It can be an array, example: ["attribute" => "value", "attribute" => "value", ...]. It can be a string containing an array in JSON format.
header
The HTTP header. It is usually an array like ["Content-Type: application/json", "Content-Length: 123456"].
method
The HTTP method. Default: POST.

Response

Returns a PHP array with the data of the JSON array returned by the server.


sb_download()

Returns the data of a URL.


Arguments

URL
The destination URL.

Response

The file or the data returned by the server.


sb_download_file()

Download a file, save it in the uploads folder, and return the URL.


Arguments

URL
The destination URL.
file_name
The file name of the saved file. Default: original file name.
mime
Set it to true to retrieve the file extension automatically. Set it to a mime type string to assign the mime extension to the file name.

Response

The URL of the file saved in the uploads folder.


sb_csv()

Create a CSV file from an array.


Arguments

items
Array containing the data to save in the CSV file. It must be a basic array, each item is a new row in the CSV file.
header
Array containing the header elements. Example: ["ID", "First Name", "Last Name", "Email"].
filename
The name of the CSV file.

Response

Returns the URL of the CSV file. The file is saved into the uploads folder. By default, it's located in the supportboard plugin folder or in the wp-content/uploads folder if you're using the WordPress version.


sb_file()

Create a new file containing the given content and save it in the destination path.


Arguments

path
The file system destination path, the file will be saved there.
content
The content of the file.

Response

                                true
                            

sb_clean_data()

This function performs the following tasks: delete visitors older than 24h, delete messages in trash older than 30 days, archive conversation older than 24h with status code equal to 0 or 1 (waiting an answer from the user or without any user reply).


Response

true

sb_cron_jobs()

Run the cron jobs.


sb_get_shortcode()

Convert a shortcode into an array containing the shortcode name and the shortcode settings.


Arguments

shortcode
The shortcode string. Example: [rating title="Rate your conversation" message="Tell us your experience." success="Thank you!"].
name
The shortcode name. Example: inputs. Default: false.
type
Set it to merge if the shortcode is a merge field like {}.

Response

                                {
                                    "shortcode": "[rating title="Rate your conversation" message="Tell us your experience." success="Thank you!"]",
                                    "shortcode_name": "rating",
                                    "title": "Rate your conversation",
                                    "message": "Tell us your experience.",
                                    "success": "Thank you!"
                                }
                            

sb_cron_jobs()

Check the cron jobs and run them if the date and time matchs the job time.


sb_css()

Returns or echos the CSS style for the chat colors.


Arguments

color_1
The first color in RGB or HEX format. Default: the first color saved in the settings area.
color_2
The second color in RGB or HEX format. Default: the second color saved in the settings area.
color_3
The third color in RGB or HEX format. Default: the third color saved in the settings area.
return
Set it to true to return the code instead of echo it. Default: false.

Response

The CSS code

sb_get_notes()

Returns the internal notes of a conversation.


Arguments

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."
                                    },
                                    ...
                                ]
                            

sb_add_note()

Add a new internal note.


Arguments

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
                            

sb_delete_note()

Delete an internal note.


Arguments

conversation_id
The ID of the conversation linked with the note.
note_id
The note ID.

Response

                                true
                            

sb_automations_get()

Returns all automations.


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"
                                                }
                                            ]
                                        },
                                        ...
                                    }
                                ]
                            

sb_automations_save()

Save all automations.


Arguments

automations
Automations array. Get it from sb_get_automations().
translations
Automations translations array. Get it from sb_get_automations().

Response

                                true
                            

sb_automations_validate()

Validate an automations.


Arguments

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.


sb_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.


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"
                                    },
                                    ...
                                ]
                            

sb_automations_run()

Execute a single automation and optionally validate it before executing it.


Arguments

automation
The automation.
validate
Set it to true to validate the automation before executing it. Default: false.

Response

                              
                                true