Preview Campaign Realtime API

The Preview Campaign Realtime API can be used to query and update the existing tasks loaded within a Symbee Connect Preview or Progressive Campaign programmatically. You can also use this API to load new Preview tasks into a Campaign, as an alternative to loading tasks using intake files uploaded via S3.

Refer here for a complete overview of the Preview and Progressive Dial Channel in general, Campaign concepts, a description of expected workflow, and discussion of uploading Preview Tasks into Campaigns using Intake Files.

Preview Campaign Realtime API Endpoint

All Preview Campaign Realtime API requests are sent as HTTP POST requests, to the following API URL prefix.
The API Action (see here) is then appended to end:

https://[global-region.]symbeeconnect.com:9443/symbee-previewcontact-service/svc/rs/PreviewContactServiceExternal/

Where [global-region.] in the above URL is one of the following, depending on which region your Symbee Connect Environment resides:

not supplied (defaults to us-east-1)
us-west-2
ca-central-1
eu-west-2
eu-central-1
ap-southeast-1
ap-southeast-2
ap-northeast-1
ap-northeast-2
af-south-1

API Authentication

All POST requests to the API must have the following additional HTTP Headers present on the requests to succeed:

X-sc-platform-code – static value of “AWS Connect”
X-sc-company-code – Your Symbee Connect Company Alias
X-sc-company-environment – Your Symbee Connect Environment name
X-sc-secrets-region – Your Symbee Connect *AWS Secrets Manager Region* e.g. “us-east-1”
X-sc-company-api-key – Your AWS Secrets Manager Symbee Connect API Key

Details on the 'X-sc-company-api-key' Header value

You will need to obtain your Symbee Connect API Key programmatically from AWS Secrets Manager.

When you sign up for Symbee Connect and decide to use any of the optional features that require running CloudFormations, the very first CloudFormation you run (see here for reference) installs an automatically rotating API Key into the AWS Account associated with the Symbee Connect Environment. This API key establishes a 2-way trust between you and Symbee Connect, and its value is required as a Header on all API requests.

To obtain the API key, use the AWS Secrets Manager API GetSecretValue action, passing in a SecretId of "SYMBEE_CONNECT_API_KEY". Use the value returned in the SecretString property of the response payload as the value to send in the 'X-sc-company-api-key'' header on Routed Email API requests.

Note that the SYMBEE_CONNECT_API_KEY value in Secrets Manager is regularly rotated, so it is best to not cache this value for an extended period of time (no longer than an hour).

API Actions Overview

The following actions are supported by the Preview Campaign Realtime API:

AddOrUpdateCampaignRecord

Allows either a new record to be added, or an existing record to be updated (replaced) in an existing Preview/Progressive Campaign. The PreviewRecordId or ClientId on the record provided in the payload is used to determine whether an Add or Update request occurs. If a record with the specified PreviewRecordId or ClientId already exists, the request results in an Update, otherwise the new record will be added.

SearchPreviewCampaign

Allows you to query the contents of an existing Preview/Progressive Campaign's current tasks/records.

Search by explicit record identifier, using either the Symbee Connect assigned unique previewRecordId, or your provided clientId, to retrieve the current details of a single specific Campaign task/record.
Search based on one or more column values to return a list of tasks/records in the Campaign that meet the specified criteria.

ChangeCampaignRecordStatus

Allows you to update the current status (NOTWORKED, WORKED, COMPLETED, REMOVED) of an existing Campaign task/record.

Each task or record within a Campaign has its fundamental status. See here for a description and understanding of each of the task states in the Preview Campaign lifecycle.

TransferCampaignRecord

Allows you to request an existing task/record in one campaign be moved to another Campaign and/or Skill Queue.

DeleteRecordFromCampaign

Used to have a task/record removed from an existing Campaign.

AddOrUpdateCampaignRecord Action

Either adds a new task/record, or updates (replaces) an existing task/record within a specified Preview or Progressive Campaign. The PreviewRecordId or ClientId on the request payload is used to determine whether an Add or Update action occurs. If a task/record with the specified PreviewRecordId or ClientId already exists, the request results in an Update, otherwise the new task/record will be added.

Action Request URL

Send requests to the following URI, see here for notes regarding the [global-region.] reference below.

https://[global-region.]symbeeconnect.com:9443/symbee-previewcontact-service/svc/rs/PreviewContactServiceExternal/addOrUpdateCampaignRecord

Action Request Payload

The Request POST payload is a JSON formatted payload (Content-Type: application/json). The payload is an object with the following properties/values:

platform

Value is a String. Required. Use the static value of "AWS Connect".

companyCode

Value is a String. Required. Use your Symbee Connect Company Alias.

environment

Value is a String. Required. Use your Symbee Connect Environment name.

campaignName

Value is a String. Required. The (case-sensitive) name of the Symbee Connect Preview or Progressive Campaign this action applies to.

region

Value is a String. Required. The AWS region where your Symbee Connect Preview or Progressive campaign resides. Example values: "us-east-1" (AWS Virginia Region), "eu-central-1" (AWS Frankfurt Region).

previewRecordId

Value is a String. Optional.

If specified, the provided value is used to locate an existing task/record for an update. If no task/record is found for the specified value, an Add is performed, and this value is then ignored (when new records are added to a campaign, the previewRecordId is a system auto-generated value, guaranteed to be unique, which is why this property is ignored if the action is determined to be an Add).

If this previewRecordId property is specified, any clientId (below) property value is ignored during the Add or Update determination. If not specified, the clientId property (below) is used to determine Add or Update behavior.

clientId

Value is a String. Required.

The value is expected to be unique within the Campaign. If no previewRecordId (see above) value is provided, this clientId is used to locate an existing task/record for an update. If no task/record is found for the specified value, an Add is performed.

clientIdFieldName

Value is a String. Optional.

This property exists to allow the Realtime API to be used in conjunction with traditional Preview Intake Files uploaded via S3 for the same Campaign. For details about adding tasks/records to a Campaign using Intake Files see here - in this reference, note specifically the treatment of the first column of each record in an Intake file (referred to as the Unique Matching ID value).

When records are added to a Campaign via an Intake file, the first column in the file is used as the Unique Matching ID. When using this API, the API payload clientId property is the equivalent to this.

When adding new records, the clientId value (above) is implicitly added to the previewRecordData automatically when the request is processed, using the key name specified in this clientIdFieldName property. If this property is not specified, a default key name of Id is used.

When working with a Campaign that is also receiving data from Intake Files, make sure you set the clientIdFieldName value to the same name as the first column (specified in the first column header row of each file) of your Intake Files, otherwise unexpected behavior may result.

preferredAgent

Value is a String. Optional.

If specified, must contain the user identifier of an agent.

If the preferred agent is not logged in or doesn't become available within 30 minutes of the task becoming available to be delivered, the agent preference will be cleared and the task will be delivered to the next best skilled agent.

nextEarliestWorkTimeUTC

Value is a Number (Long). Optional.

If specified, indicates the task/record should not be considered for delivery to an agent until the specified time has elapsed. For example, setting this property to a logical value of 2pm in the future will result in the record being added or updated in the Campaign immediately, but the task/record will not be put into queue to be worked until the after 2pm.

If specified, the value is expected to be a UTC Unix Epoch based time value (i.e. the number of milliseconds since the 1st of January, 1970).

previewRecordData

Value is an Array of objects. Required.

A list of key/value pair objects used to describe the data associated with the Preview Task being added or updated (replaced). Each object in the array has the following properties:

key - String. Required. The name of the data item.
value - String. Required. The value of the data item.
displayOrder - Integer. Optional. Controls the order of data when displayed to the Agent. If provided, must be greater than zero.

An Update action results in a deletion of all previously stored data associated with the clientId or previewRecordId, and replaced with all the new key / value data specified. Therefore to update the values of an existing record, all fields/values need to ne specified.

In addition to your custom task/record data, there are certain specially named and optional system data items (previewRecordData key's) that if present, can control behavior (e.g., highlighting, buttons, links, click-to-call, etc.) when the task/record is routed and displayed to the agent. See the following table for special field key names and their resulting treatment.

KEY NAME CHARACTERISTIC	TREATMENT
Name	If a key/value pair with a key named exactly '*Name' is present (and strongly recommended to be), the value of the key/value pair is expected to be a String. The value is used as the top banner for the preview task when presented to the agent. There can be (and usually are) other names present in the record also, that are presented to the Agent in the Details* section of the task as needed. The value of this explicit Name key is not displayed in the Details section of the task to the Agent – it is only used in the banner. If you need the value to be displayed in the Details section as well, repeat the value in your record data using a different key name (e.g. Full Name, or Customer Name, etc).
Phone Numbers	Any key/value pair with a key name containing the word “phone” (case-insensitive) (e.g. phone, homePhone, phoneMobile) is treated as a phone number, with a “click to dial” icon added to it. Format of phone number values need to be clean E.164 (e.g. +17202321123, +4472612321)
Highlighting specific fields	An optional key/value pair with a key named Highlight can be defined in your preview record data. If present in the record, this key/value pair will be hidden when items are delivered to the Agent. If a record contains a Highlight key/value pair, the value is expected to be a String. Specifically, a pipe-delimited list of key names indicating other key/value pairs in the record that should be highlighted when presented to the user. As an example: AccountBalance\|OverdueAmount\|DueDate. A special value of “ALL” is also supported, which results in all fields in the current record being highlighted when presented to the user.
Hiding specific fields	An optional key/value pair with a key named Hidden can be defined in your preview record data. This allows you to add data to your record that might be useful in backend or integration processing, or for tracking and troubleshooting, but that you don't want to be displayed to the user. If present in the record, this key/value pair will also itself be hidden when items are delivered to the Agent. If a record contains a Hidden key/value pair, the value is expected to be a String. Specifically, a pipe-delimited list of key names indicating other key/value pairs in the record that should be hidden and not presented to the user. As an example: TransactionId\|CreateDate\|EventId.
_link keys	For any key/value pair with a key name ending with the exact string of “_link”, for example “AccountLookup_link”, the value for the key/value pair is expected to be a URL. This results in the value being presented as a URL link, with the field label being the key name (with the “_link” removed off the end). If the link is clicked by the user, the respective URL will be opened is a separate window outside of the Symbee Connect Agent UI.
_button keys	For any key/value pair with a key name ending with the exact string of “_button”, for example “AccountLookup_button”, the value for the key/value pair is expected to be a URL. This results in a button being displayed instead of a normal field. The label on the button is the key name (with the “_button” removed off the end). If the button is clicked by the user, the respective URL will be opened is a separate window outside of the Symbee Connect Agent UI.
Queue Distribution	An optional key/value pair with a key named SkillQueue can be defined in your preview record data. If present, this key/value pair will be hidden when items are delivered to the Agent. If present, the value of the key/value pair is expected to be a String, and must contain a valid Skill Queue code (this is the name of the Queue) defined within your Symbee Connect Environment, indicating the task defined by that record should be serviced through the specified Skill Queue. If not present, the task will be serviced through the Default Skill Queue configured on the Campaign.
Time Zone	An optional key/value pair named ItemTimeZone can be defined in your preview record data. If present, this key/value pair's value indicates the Time Zone treatment that should be used for the record. The value for this column is a valid Time Zone per the IANA Time Zone Database (TZDB). For reference, refer to the TZ database name column of the following Wikipedia page: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones If not present, the task will be treated using the Default Time Zone configured on the Campaign

Request Payload Example

The following example is a request to update the existing task/record with the internal identifier of "9e108fff-f369-4921-87fe-7d1656006dd4", setting the tasks preferred agent, and an earliest time to be worked of 2021/11/05 14:15:00 UTC. The record data also indicates to display a Customer Search button (backed with the specified URL), and to highlight the Open Invoice Total data value when displayed to the agent.

{
    "platform" : "AWS Connect",
    "companyCode" : "abc-gadgets",
    "environment" : "prod",
    "region" : "us-east-1",
    "campaignName" : "WebsiteVisitReachouts",
    "previewRecordId" : "9e108fff-f369-4921-87fe-7d1656006dd4",
    "clientIdFieldName": "KeyId",
    "clientId" : "A2-12769-812",
    "preferredAgent" : "jtester@abc-gadgets.com",
    "nextEarliestWorkTimeUTC" : 1636121700000,
    "previewRecordData" : [
        {
            "key" : "Name",
            "value" : "Kate Delaney",
            "displayOrder" : 1
        }, 
        {
            "key" : "Open Invoice Total",
            "value" : "$576.35",
            "displayOrder" : 2
        }, 
        {
            "key" : "Home Phone",
            "value" : "+15552101257",
            "displayOrder" : 3
        } 
        {
            "key" : "Customer Search_button",
            "value" : "https://crm.abc-gadgets.com/customer/lookup?id=A2-12769-812",
            "displayOrder" : 4
        }, 
        {
            "key" : "Highlight",
            "value" : "Open Invoice Total",
        }, 
    ]
}

Action Response Payload

Standard HTTP Response Codes are used as responses. Therefore HTTP 4xx and 5xx response codes should be treated as failure. An HTTP 200 OK response may also indicate some other type of request failure based on the value of the previewResultStatus property in the response.

An HTTP 200 OK will return a JSON payload containing an object with an inner previewResult object describing the outcome of the action request. The previewResult object has the following properties:

previewResult.previewResultStatus

Value is a String. One of the following values:

SUCCESS - the requested action was successful.
FAILED - the requested action failed. Refer to previewResult.error (below) for the failure reason.
INVALIDCLIENTID - the request failed due to no clientId value provided
INVALIDRECORDDATAKEY - the request failed due to a key being present in the previewRecordData array with the same name as the specified clientIdFieldName

previewResult.error

Value is a String. Only relevant if previewResult.previewResultStatus (above) is not set to SUCCESS.

A string (error message) indicating the reason for the failure.

Response Payload Example:

The following is a response payload example for a successful action request.

{
    "platform": "AWS Connect",
    "companyCode": "abc-gadgets",
    "environment": "prod",
    "region": "us-east-1",
    "campaignName": "WebsiteVisitReachouts",
    "previewResult": {
        "previewResultStatus": "SUCCESS",
        "error": null
    }
}

SearchPreviewCampaign Action

Performs a query of an existing Preview/Progressive Campaign's current tasks/records.

Use the previewRecordId or clientId properties in the request payload (see below) to retrieve the details of a specific single record, in which case the response will only return a maximum of 1 task/record.

Otherwise, use the previewRecordData object, and associated maxRecords properties in the request payload to search and return records matching a given criteria.

Action Request URL

Send requests to the following URI, see here for notes regarding the [global-region.] reference below.

https://[global-region.]symbeeconnect.com:9443/symbee-previewcontact-service/svc/rs/PreviewContactServiceExternal/searchPreviewCampaign

Action Request Payload

The Request POST payload is a JSON formatted payload (Content-Type: application/json). The payload is an object with the following properties/values:

platform

Value is a String. Required. Use the static value of "AWS Connect".

companyCode

Value is a String. Required. Use your Symbee Connect Company Alias.

environment

Value is a String. Required. Use your Symbee Connect Environment name.

campaignName

Value is a String. Required. The (case-sensitive) name of the Symbee Connect Preview or Progressive Campaign this action applies to.

region

previewRecordId

Value is a String. Optional.

If specified, the provided value is used to locate a specific single task/record in the specified Campaign. If no task/record is found for the specified value, a NORECORDFOUND response will be returned.

If this previewRecordId property is specified, any clientId (below) property value is ignored.

clientId

Value is a String. Optional. This value is ignored if the previewRecordId (above) is also provided.

maxRecords

Value is an Integer. Optional. Only relevant when previewRecordId and clientId are not provided.

Specifies the maximum number of records to return in the response payload. If not specified a default of 1000 will be used.

previewRecordData

Value is an Array of key/value pair objects. Not required when previewRecordId or clientId are provided. Otherwise required.

A list of key/value pair objects used to describe the criteria to be used for the search. Each object in the array has the following properties:

key - String. Required. The name of the data item used for the search criteria.
value - String. Required. The value used for the search.
condition - String. Required. One of the following values: EQUALS, NOTEQUALS, GREATERTHAN, LESSTHAN, CONTAINS, BEGINSWITH

The name of any of your custom record data fields can be used (set as the key) in the above search criteria. Additionally the following system fields can also be specified as the key:

sys_skill_queue - The Symbee Connect Skill Queue name the task/record is currently set to.
sys_worked_attempts - The number of times the task/record has been attempted to be worked (delivered to an agent).
sys_item_time_zone - The time zone set on the task/record
sys_worked_state - The task/record status (one of NOTWORKED, WORKED, COMPLETED, or REMOVED).
sys_preferred_agent - The user id of a preferred agent (if set) on the task/record.
sys_next_earliest_worktime_long - The currently set earliest next work time on the task/record (if set). The value is expected to be a UTC Unix Epoch based time value (i.e. the number of milliseconds since the 1st of January, 1970).

Request Payload Examples

Example request payload of a query for a specific record using previewRecordId

{
    "platform" : "AWS Connect",
    "companyCode" : "abc-gadgets",
    "environment" : "prod",
    "region" : "us-east-1",
    "campaignName": "WebsiteVisitReachouts",
    "previewRecordID" : "e94c0a8a-0b69-11ec-9a03-0242ac130003"
}

Example request payload of a query for specific record using clientId

{
    "platform" : "AWS Connect",
    "companyCode" : "abc-gadgets",
    "environment" : "prod",
    "region" : "us-east-1",
    "campaignName": "WebsiteVisitReachouts",
    "clientId" : "1022"
}

Example request payload of query for records matching a set of criteria

{
    "platform" : "AWS Connect",
    "companyCode" : "abc-gadgets",
    "environment" : "prod",
    "region" : "us-east-1",
    "campaignName": "WebsiteVisitReachouts",
    "maxRecords" : 50
    "previewRecordData" : [
        {
            "key" : "sys_worked_state",
            "value" : "NOTWORKED",
            "condition": "EQUALS"
        },
        {
            "key" : "name",
            "value" : "Johnny Tester",
            "condition": "EQUALS"
        }
    ]
}

Action Response Payload

previewResult.previewResultStatus

Value is a String. One of the following values:

SUCCESS - the requested action was successful.
FAILED - the requested action failed. Refer to previewResult.error (below) for the failure reason.

previewResult.error

Value is a String. Only relevant if previewResult.previewResultStatus (above) is not set to SUCCESS.

A string (error message) indicating the reason for the failure.

List of matched Tasks/Records (previewRecordClientData)

in addition to the above, the response payload returns the set of matched tasks/records in the previewRecordClientData object array. Each object in the previewRecordClientData array has the following properties:

previewRecordID

Value is a String. The internal unique identifier assigned to the task/record within the Campaign.

clientId

Value is a String. The unique identifier you set (during data load) for the task/record within the Campaign.

preferredAgent

Value is a String. The user identifier of the agent preferred to work this task/record.

May be null or empty-string ("") if no preferred agent currently set on the task/record.

skillQueue

Value is a String. The name of a Symbee Connect Skill Queue the task/record will be delivered through.

createdTime

Value is a String. A UTC date/time string in the format of: "CCYY-MM-DD HH:MM:SS.mmm".

The date/time in UTC the record was originally added to the Campaign.

lastUpdatedTime

Value is a String. A UTC date/time string in the format of: "CCYY-MM-DD HH:MM:SS.mmm".

The date/time in UTC the record was last updated by Campaign processing.

nextEarliestWorkTime

Value is a String. May be null. If not null, a UTC date/time string in the format of: "CCYY-MM-DD HH:MM:SS.mmm".

Indicates the next date/time, in UTC, the task/record will be able to be considered for delivery to an agent.

workedState

Value is a String. The current Campaign lifecycly work state for the task/record. Will be one of: NOTWORKED, WORKED, COMPLETED, or REMOVED.

workAttempts

Value is an Integer. The number of times the task/record has been worked by an agent. 0 (zero) indicates not yet worked, greater than 0 indicates the task/record has been worked at least once, but may be scheduled for another future attempt (if workedState is still set to WORKED).

lastAttemptAgent

Value is a String. The user identifier of the agent that worked the last attempt on the this task/record.

Will be null or empty-string ("") if the task/record has not yet been worked (when workedState is still set to NOTWORKED).

lastAttemptTime

Value is a String. A UTC date/time string in the format of: "CCYY-MM-DD HH:MM:SS.mmm".

The time of the last attempt (time last delivered to an agent) for the task/record. Will be null or empty-string ("") if the task/record has not yet been worked (when workedState is still set to NOTWORKED).

workCodes

Value is an array of objects.

If the task/record has been worked by an agent and the agent set/assigned work code(s) when completing the task/record, each object in this array has a key and value property (both Strings) indicating the selected work code (the value) and the work code group (the key) the selected work code was part of.

previewRecordData

Value is an Array of key/value pair objects.

A list of key/value pair objects used to describe the data of the task/record. Each object in the array has the following properties:

key - String. The name of the data item.
value - String. The value of the data item.
displayOrder - Integer. A value indicating the order the data is displayed to the Agent.

Response Payload Example:

The following is a response payload example for a successful search request.

{
    "platform" : "AWS Connect",
    "companyCode" : "abc-gadgets",
    "environment" : "prod",
    "region" : "us-east-1",
    "campaignName": "WebsiteVisitReachouts",
    "previewResult": {
        "previewResultStatus": "SUCCESS",
        "error": null
    },
    "previewRecordClientData": [
        {
            "previewRecordID": "8a22f4ec-50b9-4229-9d09-5387b86d590d",
            "clientId": "1021",
            "preferredAgent" : "",
            "skillQueue": "WebsiteVisits",
            "createdTime": "2021-11-03 05:01:05.120",
            "lastUpdatedTime": "2021-11-03 21:28:17.035",
            "nextEarliestWorkTime": "2021-11-03 22:00:00.000",
            "workedState": "WORKED",
            "workAttempts": 1,
            "lastAttemptAgent": "jtester@abc-gadgets.com",
            "lastAttemptTime": "2021-11-03 21:28:17.035",
            "workCodes": [
                {
                    "key": "Visit Reachout Actions",
                    "value": "Not Interested"
                }
            ],
            "previewRecordData": [
                {
                    "key": "ID",
                    "value": "A2-12769-812",
                    "displayOrder": 0
                },
                {
                    "key": "Company Name",
                    "value": "Sunshine Postal LLC",
                    "displayOrder": 1
                },
                {
                    "key": "Name",
                    "value": "Mike Mars",
                    "displayOrder": 2
                },
                {
                    "key": "Account Number",
                    "value": "7621345",
                    "displayOrder": 3
                },
                {
                    "key": "Open Invoice Total",
                    "value": "$2,378.00",
                    "displayOrder": 4
                },
                {
                    "key": "Home Phone",
                    "value": "+15552101257",
                    "displayOrder": 5
                },
                {
                    "key": "Mobile Phone",
                    "value": "+15552106621",
                    "displayOrder": 6
                },
                {
                    "key": "Highlight",
                    "value": "Open Invoice Total|Account Number",
                    "displayOrder": 10
                },
                {
                    "key": "Customer Search_button",
                    "value": "https://crm.abc-gadgets.com/customer/lookup?id=A2-12769-812",
                    "displayOrder": 11
                },
            ]
        }
    ]
}

ChangeCampaignRecordStatus Action

Updates the current status (NOTWORKED, WORKED, COMPLETED, REMOVED) and related system fields of a specified task/recording in a Campaign, controlling the future delivery behavior for the task.

Each task or record within a Campaign has its fundamental status. See here for a description and understanding of each of the task states in the Preview Campaign lifecycle.

Action Request URL

Send requests to the following URI, see here for notes regarding the [global-region.] reference below.

https://[global-region.]symbeeconnect.com:9443/symbee-previewcontact-service/svc/rs/PreviewContactServiceExternal/changeCampaignRecordStatus

Action Request Payload

The Request POST payload is a JSON formatted payload (Content-Type: application/json). The payload is an object with the following properties/values:

platform

Value is a String. Required. Use the static value of "AWS Connect".

companyCode

Value is a String. Required. Use your Symbee Connect Company Alias.

environment

Value is a String. Required. Use your Symbee Connect Environment name.

campaignName

Value is a String. Required. The (case-sensitive) name of the Symbee Connect Preview or Progressive Campaign this action applies to.

region

previewRecordId

Value is a String. Optional.

If specified, the provided value is used to locate the specific task/record in the specified Campaign to action on. If no task/record is found for the specified value, a NORECORDFOUND response will be returned.

If this previewRecordId property is specified, any clientId (below) property value is ignored.

clientId

Value is a String. Optional. This value is ignored if the previewRecordId (above) is also provided.

previewRecordStateEnum

Value is a String. Required.

The new work status to update the specified record to. Must be one of the following values:

NOTWORKED
WORKED
COMPLETED
REMOVED

skillQueue

Value is a String. Optional. The name of a Symbee Connect Skill Queue.

If provided, updates the SkillQueue on the located task/record to be delivered through the Symbee Connect Skill Queue specified.

preferredAgent

Value is a String. Optional.

If specified, must contain the user identifier of an agent. If specified with an empty-string ("") value, clears any previously assigned preferred agent that was set.

When a Preview task/record with a preferred agent set becomes available to be worked, the ACD will attempt to deliver the task to the specified preferred agent when they are logged in and become available. If the preferred agent is not logged in or doesn't become available within 30 minutes of the task becoming available to be delivered, the agent preference will be cleared and the task will be delivered to the next best skilled agent.

nextEarliestWorkTimeUTC

Value is a Number (Long). Required if the previewRecordStateEnum (see above) property is set to WORKED, otherwise optional.

When specified, indicates the task/record should not be considered for delivery to an agent until the specified time has elapsed. For example, setting this property to a logical value of 2pm in the future will result in the record being added or updated in the Campaign immediately, but the task/record will not be put into queue to be worked until the after 2pm.

The value is expected to be a UTC Unix Epoch based time value (i.e. the number of milliseconds since the 1st of January, 1970).

timeZone

Value is a String. Optional.

When provided, sets the time zone on the task/record specified. This value indicates the Time Zone treatment that should be used for the task/record. The value is a valid Time Zone per the IANA Time Zone Database (TZDB). For reference, refer to the TZ database name column of the following Wikipedia page: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Request Payload Example

Example request payload for updating a task/record based on clientId back to NOTWORKED, setting a preferred agent, and an earliest next work time.

{
    "platform" : "AWS Connect",
    "companyCode" : "abc-gadgets",
    "environment" : "prod",
    "region" : "us-east-1",
    "campaignName" : "WebsiteVisitReachouts",

    "clientId" : "1022",

    "skillQueue" : "WebsiteVisits", 
    "nextEarliestWorkTimeUTC" : 1636121700000, 
    "preferredAgent" : "jtester@abc-gadgets.com",
    "timeZone" : "Europe/Berlin",
    "previewRecordStateEnum" : "NOTWORKED"
}

Action Response Payload

previewResult.previewResultStatus

Value is a String. One of the following values:

SUCCESS - the requested action was successful.
FAILED - the requested action failed. Refer to previewResult.error (below) for the failure reason.

previewResult.error

Value is a String. Only relevant if previewResult.previewResultStatus (above) is not set to SUCCESS.

A string (error message) indicating the reason for the failure.

Response Payload Example:

The following is a response payload example for a successful change status request.

{
    "platform" : "AWS Connect",
    "companyCode" : "abc-gadgets",
    "environment" : "prod",
    "region" : "us-east-1",
    "campaignName" : "WebsiteVisitReachouts",
    "previewResult": {
        "previewResultStatus": "SUCCESS",
        "error": null
    }
}

TransferCampaignRecord Action

Moves an existing task/record in one campaign to another Campaign and/or Skill Queue.

Action Request URL

Send requests to the following URI, see here for notes regarding the [global-region.] reference below.

https://[global-region.]symbeeconnect.com:9443/symbee-previewcontact-service/svc/rs/PreviewContactServiceExternal/transferCampaignRecord

Action Request Payload

The Request POST payload is a JSON formatted payload (Content-Type: application/json). The payload is an object with the following properties/values:

platform

Value is a String. Required. Use the static value of "AWS Connect".

companyCode

Value is a String. Required. Use your Symbee Connect Company Alias.

environment

Value is a String. Required. Use your Symbee Connect Environment name.

campaignName

Value is a String. Required. The (case-sensitive) name of the Symbee Connect Preview or Progressive Campaign the specified task/record is currently part of.

region

previewRecordId

Value is a String. Optional.

If this previewRecordId property is specified, any clientId (below) property value is ignored.

clientId

Value is a String. Optional. This value is ignored if the previewRecordId (above) is also provided.

transferToCampaign

Value is a String. Required.

The (case-sensitive) name of the Symbee Connect Preview or Progressive Campaign to transfer the identified task/record to.

skillQueue

Value is a String. Optional. The name of a Symbee Connect Skill Queue.

If provided, updates the SkillQueue on the located task/record to be delivered through the Symbee Connect Skill Queue specified.

preferredAgent

Value is a String. Optional.

If specified, must contain the user identifier of an agent. If specified with an empty-string ("") value, clears any previously assigned preferred agent that was set.

nextEarliestWorkTimeUTC

Value is a Number (Long). Optional.

The value is expected to be a UTC Unix Epoch based time value (i.e. the number of milliseconds since the 1st of January, 1970).

timeZone

Value is a String. Optional.

Request Payload Example

Example request payload for transferring a task/record based on clientId from Campaign WebsiteVisitReachouts to Campaign WebsitVisitFollowups, also setting a preferred agent, and an earliest next work time.

{
    "platform" : "AWS Connect",
    "companyCode" : "abc-gadgets",
    "environment" : "prod",
    "region" : "us-east-1",
    "campaignName" : "WebsiteVisitReachouts",

    "clientId" : "111111",

    "transferToCampaign" : "WebsitVisitFollowups",
    "skillQueue" : "WebsiteFollowups",
    "nextEarliestWorkTimeUTC" : 1636121700000, 
    "preferredAgent" : "jtester@abc-gadgets.com",
    "timeZone" : "Europe/Berlin",
}

Action Response Payload

previewResult.previewResultStatus

Value is a String. One of the following values:

SUCCESS - the requested action was successful.
FAILED - the requested action failed. Refer to previewResult.error (below) for the failure reason.

previewResult.error

Value is a String. Only relevant if previewResult.previewResultStatus (above) is not set to SUCCESS.

A string (error message) indicating the reason for the failure.

Response Payload Example:

The following is a response payload example for a successful transfer request.

{
    "platform" : "AWS Connect",
    "companyCode" : "abc-gadgets",
    "environment" : "prod",
    "region" : "us-east-1",
    "campaignName" : "WebsiteVisitReachouts",
    "previewResult": {
        "previewResultStatus": "SUCCESS",
        "error": null
    }
}

DeleteRecordFromCampaign Action

Removes a task/record from an existing Campaign.

Action Request URL

Send requests to the following URI, see here for notes regarding the [global-region.] reference below.

https://[global-region.]symbeeconnect.com:9443/symbee-previewcontact-service/svc/rs/PreviewContactServiceExternal/deleteRecordFromCampaign

Action Request Payload

The Request POST payload is a JSON formatted payload (Content-Type: application/json). The payload is an object with the following properties/values:

platform

Value is a String. Required. Use the static value of "AWS Connect".

companyCode

Value is a String. Required. Use your Symbee Connect Company Alias.

environment

Value is a String. Required. Use your Symbee Connect Environment name.

campaignName

Value is a String. Required. The (case-sensitive) name of the Symbee Connect Preview or Progressive Campaign the specified task/record is currently part of.

region

previewRecordId

Value is a String. Optional.

If specified, the provided value is used to locate the specific task/record in the specified Campaign to remove. If no task/record is found for the specified value, a NORECORDFOUND response will be returned.

If this previewRecordId property is specified, any clientId (below) property value is ignored.

clientId

Value is a String. Optional. This value is ignored if the previewRecordId (above) is also provided.

Request Payload Example

Example request payload for a request to remove a task/record based on clientId from Campaign WebsiteVisitReachouts.

{
    "platform" : "AWS Connect",
    "companyCode" : "abc-gadgets",
    "environment" : "prod",
    "region" : "us-east-1",
    "campaignName" : "WebsiteVisitReachouts",    
    "clientId" : "111111",
}

Action Response Payload

previewResult.previewResultStatus

Value is a String. One of the following values:

SUCCESS - the requested action was successful.
FAILED - the requested action failed. Refer to previewResult.error (below) for the failure reason.

previewResult.error

Value is a String. Only relevant if previewResult.previewResultStatus (above) is not set to SUCCESS.

A string (error message) indicating the reason for the failure.

Response Payload Example:

The following is a response payload example for a successful transfer request.

{
    "platform" : "AWS Connect",
    "companyCode" : "abc-gadgets",
    "environment" : "prod",
    "region" : "us-east-1",
    "campaignName" : "WebsiteVisitReachouts",
    "previewResult": {
        "previewResultStatus": "SUCCESS",
        "error": null
    }
}