Bold360 and BoldChat Developer Center

Set up your account to work with the API

To use the Bold360 API, you must first create an API key for authentication and then define Bold360 events that trigger API calls.

Task 1: Create an API Setting key

An API setting key is required for authenticating REST API calls to the Bold360 servers.

  1. At admin.bold360.com, go to Integrations > API Settings and click Create New.
  2. Name your API key and make sure it is Enabled.
  3. Save your API key.
    Important: Do not forget to save the provided API setting key. For security reasons, the secret key will be obfuscated once the new setting is created and subsequently, only the partial API setting key will be visible.
Tip: You can disable the API setting key any time. When an API setting is disabled (unchecked) then all API calls to the Bold360 servers will be refused. Triggers within the agent workspace will continue to fire normally, but your server will not be able to communicate back to the Bold360 servers.

Task 2: Create an API trigger

An API trigger defines the conditions of an API call to be invoked.

  1. At admin.bold360.com, go to Integrations > API Triggers and click Create New.
    Option Description
    Name Defines the name for the Integrations API Trigger. The first character will identify this trigger on the agent workspace.
    URL

    Submission URL of the REST API POST data. The URL must be a fully qualified domain name (FQDN) with a proper SSL certificate configuration. IP addresses will not work.

    Important: URLs not adhering to these specifications will result in the trigger never being fired.

    For more information on security, see t_api_security.html#concept_DC47FEF541BB4AB9A28D1D623ED9A12F.

    API Key Required for authenticating REST API calls to the Bold360 servers. The API Key setting determines which API Key will be used when there is a callback return URL parameter selected on the Parameters tab. The API Key will be included as a parameter of these callback URLs so it will not be necessary to add them yourself.
    Connection Select this option to use HTTP Basic Authentication for connecting to your web application if that is required. Enter your username and password in the appropriate fields.
    Item Type

    Lists all items that determine how this trigger will activate.

    Possible options are:

    • Chats
    • Emails
    • Ticket
    • SMS
    • Facebook Messenger
    • Twitter
    • Agents
    URL Type

    The URL type defines what type of action this API trigger will do.

    Possible options are:

    for non-Agent Item Types
    • Hidden Asynchronous Action: When a Condition is met the trigger will fire an asynchronous call to your server. This will not be visible to the agent. Available for Chats, Emails, Tickets, SMS, Facebook Messenger, and Twitter Item Types
    • Hidden Synchronous Action: When a Condition is met the trigger will fire a synchronous call to your server, it will block for no longer than 15 seconds. This will not be visible to the agent. Available for Chats Item Type
    • Agent Auto-Show: When the agent opens the chat the trigger will automatically fire. Available for SMS and Facebook Messenger Item Types
    • Agent Button: An agent will click a button to cause the trigger to fire. This is a button that appears in the Bold360 agent workspace when a chat appears and gives the agent an option to display an iframe of the URL provided. Available for Chats, SMS, and Facebook Messenger Item Types
    for Agents Item Type
    • Agent [Message type] Count Changed: When there is a change in the number of active messages for an agent on a specific channel, agent details and the chosen parameters are asynchronously posted to the specified URL.
    • Agent [Channel type] Status Changed: When an agent's status changes for a channel (online/away/offline), agent details and the chosen parameters are asynchronously posted to the specified URL.
    View

    The View setting becomes available after selecting an agent initiated Trigger Type. This setting determines how the web page is opened when the agent causes the trigger to fire.

    Possible options are:
    • Tab: A new tab in the details section for the chat will open.
    • Dock: A docked view will open next to the chat so both are visible at the same time. By default this view will be on to the right of the chat.
    • Pop Up: A new pop-up window will open with the content.
    • Embedded: A new panel next to the chat panel for the Agent Button will open.
    Condition

    The Condition setting determines when the trigger will be fired. Depending on the Item type that is selected you can choose to fire the trigger only on specific events, or add all the types to fire the trigger for each type of events. This option is only available for the hidden action URL types.

    Restriction: Applies to postback event types only.
    • xChat window is closed: Triggered when the chat window has been fully completed, and is closed.
    • x Chat is created: Triggered when the user has clicked the chat button, but the chat has not yet started, while the user is still filling out the pre-chat form for example.
    • xChat is started: Triggered when the chat has started. This is the point where the chat appears in the Active Chats grid view.
    • xChat is answered:Triggered when an agent has answered the chat.
    • Chat is ended: Triggered when the chat has ended.
    • Started Chat was closed: Triggered when the agent or customer closes the chat, or the chat auto ends and closes.
    • x Chat is reassigned: Triggered when ACD or an agent re-assigns the chat to another agent, or changes department.
    • xChat is unassigned: Triggered when ACD or an agent unassigns a chat from an agent.
    • Chat Page: Triggered after the customer has been shown the chat page.
    • Post-Chat Page: Triggered after the customer has been shown the Post-Chat page.
    • Unavailable Page: Triggered after the customer has been shown the chat is unavailable page (or unavailable email form).
    • Pre-Chat Page: Triggered after the customer has been shown the Pre-Chat page.
    • Post-Chat Submit Page: Triggered after the customer has submitted the post-chat form. This is the very last step before a chat window closes.
    • Unavailable Submit Page: Triggered after the customer has submitted the unavailable email form. This is the very last step before a chat window closes.
    • x Chat message is added: Triggered when a chat message is added to a chat.
    Filters

    The filters list allows you to define additional criteria before the trigger fires and make the call to your server. Several filter types are supported. For a trigger to fire, all criteria across filter types must be met. Within a filter type (such as Department), only one of the selected items needs to match.

    Parameters The Parameters list defines which parameters are passed when the API trigger call is made to your server. To add a parameter, click New.
    Note: There are two components of a parameter entry:
    • Field: The internal name of the parameter as used by the service.
    • Parameter: The parameter name that will be used in the URL when a call is made to your server. For a list of supported parameters, see Supported API trigger parameters.
    Important: You must select the fields you want included in cases when the configured trigger submits a JSON object. Fields are passed with the name selected in an object with the parameter name.

    Applies to Chat Transcript, Operator and Department parameters.

    For example, the following object is returned if Text, Name and Created Fields are selected for the Chat Transcript parameter:

    {
      "ChatTranscript":
        [
          {"Name":"Customer","Text":"Hello there","Created":"2014-10-29T20:35:54.273Z"},
          {"Name":"Operator","Text":"How may I help you?","Created":"2014-10-29T20:36:12.275Z"},
          {"Name":"Customer","Text":"I think I figured it out. Goodbye.","Created":"2014-10-29T20:36:20.142Z"}
        ]
    }

    You can choose the following types of parameters for Chat and Operator Items:

    Chats

    • Standard: Predefined parameters supported by the Chats service. Select the Field from the list and change the name of the parameter to be passed.
    • Custom Field in Pre-Chat or Post-Chat: Custom fields, as defined in the Pre-Chat and Post-Chat form configurations. Simply type the name of the CustomField and change the name of the parameter that will be passed.
    • Custom Field in Agent Wrap-Up: Custom fields, as defined in the Agent Wrap-Up configuration. Simply type the name of the CustomField and change the name of the parameter that will be passed.
    • Chat Transcript: Submits a JSON object containing all chat messages.

    • Chat Message: Parameter for the Chat message is added Trigger. Returns the chat message field for the message that was added.
    • Operator: Submits a JSON object containing the agent details to whom the chat is assigned.
    • Department: Submits a JSON object containing the department details to which the chat belongs.

    Agents

    • Standard: Predefined parameters available for the Agent Item. Select the Field from the list and change the name of the parameter to be passed.
    URL Parameters

    The URL setting determines which web page gets opened when this trigger's conditions are met. The settings under the Parameters group are passed into this URL. Typically, the URL is a url to your ticketing or CRM system.

    The HTTP method type (GET or POST) varies depending on the chosen Type.
    • POST: Hidden and Visitor types
    • GET: Agents types
  2. On the Parameters tab, click New Parameter to customize what parameters get passed into your web application. Depending on the selected Item Type, you can define the following types of parameters:

    Note: There are two components of a parameter entry:
    • Field: The internal name of the parameter as used by the service.
    • Parameter: The parameter name that will be used in the URL when a call is made to your server.
    Important: You must select the fields you want included in cases when the configured trigger submits a JSON object. Fields are passed with the name selected in an object with the parameter name.

    Option Description
    Chats
    • Standard: Predefined parameters supported by the Chats service. Select the Field from the list and change the name of the parameter to be passed.
    • Custom Field in Pre-Chat or Post-Chat: Custom fields, as defined in the Pre-Chat and Post-Chat form configurations. Simply type the name of the CustomField and change the name of the parameter that will be passed.
    • Custom Field in Agent Wrap-Up: Custom fields, as defined in the Agent Wrap-Up configuration. Simply type the name of the CustomField and change the name of the parameter that will be passed.
    • Chat Transcript: Submits a JSON object containing all chat messages.

    • Chat Message: Parameter for the Chat message is added Trigger. Returns the chat message field for the message that was added.
    • Operator: Submits a JSON object containing the agent details to whom the chat is assigned.
    • Department: Submits a JSON object containing the department details to which the chat belongs.
    Emails
    • Standard: Predefined parameters supported by the Emails service. Select the Field from the list and change the name of the parameter to be passed.
    • Email History: Submits a JSON object containing all emails.

    • Email: Parameter for the Email message is added Trigger. Returns the chat message field for the message that was added.
    • Operator: Submits a JSON object containing the agent details to whom the email is assigned.
    • Department: Submits a JSON object containing the department details to which the email belongs.
    Tickets
    • Standard: Predefined parameters supported by the Tickets service. Select the Field from the list and change the name of the parameter to be passed.
    • Operator: Submits a JSON object containing the agent details to whom the ticket is assigned.
    • Department: Submits a JSON object containing the department details to which the ticket belongs.
    SMS
    • Standard: Predefined parameters supported by the SMS service. Select the Field from the list and change the name of the parameter to be passed.
    • Authenticated URLs:
    • Message History: Submits a JSON object containing all SMS messages.

    • Message: Parameter for the SMS message is added Trigger. Returns the SMS message field for the message that was added.
    • Operator: Submits a JSON object containing the agent details to whom the SMS is assigned.
    • Department: Submits a JSON object containing the department details to which the SMS belongs.
    Facebook Messenger
    • Standard: Predefined parameters supported by the Facebook Messenger service. Select the Field from the list and change the name of the parameter to be passed.
    • Authenticated URLs:
    • Message History: Submits a JSON object containing all Facebook Messenger conversations.

    • Message: Parameter for the Facebook message is added Trigger. Returns the Facebook Messenger message field for the message that was added.
    • Operator: Submits a JSON object containing the agent details to whom the Facebook Messenger conversation is assigned.
    • Department: Submits a JSON object containing the department details to which the Facebook Messenger conversation belongs.
    Twitter
    • Standard: Predefined parameters supported by the Twitter service. Select the Field from the list and change the name of the parameter to be passed.
    • Tweet History: Submits a JSON object containing all Tweets.

    • Tweet: Parameter for the Twitter message is added Trigger. Returns the Twitter message field for the message that was added.
    • Operator: Submits a JSON object containing the agent details to whom the Tweet is assigned.
    • Department: Submits a JSON object containing the department details to which the Tweet belongs.
    Agents
    • Standard: Predefined parameters available for the Agents Item. Select the Field from the list and change the name of the parameter to be passed.
  3. On the Filters tab, you can define additional criteria before the trigger fires and make the call to your server. For a trigger to fire, all criteria across filter types must be met. Within a filter type (such as Department), only one of the selected items needs to match.
  4. Save your changes.

After successful setup, the following object is returned if, for example, the Text, Name and Created Fields are selected for the Chat Transcript parameter:

{
  "ChatTranscript":
    [
      {"Name":"Customer","Text":"Hello there","Created":"2014-10-29T20:35:54.273Z"},
      {"Name":"Operator","Text":"How may I help you?","Created":"2014-10-29T20:36:12.275Z"},
      {"Name":"Customer","Text":"I think I figured it out. Goodbye.","Created":"2014-10-29T20:36:20.142Z"}
    ]
}

For API triggers that use an Agent Button URL type, on the agent screen, when a chat appears there will be a button for all API triggers that have the URL Type Agent Button on the top right hand corner. Clicking those buttons, which are the first letters of the API trigger name, will open the panels next to the chat window for the agent to reference during the chat.