The Bright Pattern Contact Center (BPCC) Task Routing API v1 is a RESTful API that enables external systems (such as CRMs) to create, route, modify, cancel, and query tasks in BPCC.
\nThe Task Routing API v1 supports the following:
\nQueue Task: Create and queue a new task, associating it with a case and a contact.
\nCancel Task: Remove a specific task from the queue and set its disposition.
\nCancel Service Tasks: Cancel all queued tasks associated with a particular service.
\nUpdate Task: Modify attributes of a queued task, such as its service or priority.
\nQuery Task: Retrieve the status and queue information for a specific task.
\nSupport for external identifiers: Entities can be referenced using either internal (automatically generated by BPCC) or external (user provided) identifiers.
\nThis API interacts with the following core objects within Bright Pattern Contact Center:
\nTask: A discrete unit of work representing a specific action or activity to be completed by an agent. Tasks are always associated with a case and contact. When a task is queued, it may be associated with an external identifier. Existing tasks may be canceled, updated, and queried by their internal or external identifiers.
\nCase: A grouping of communications and information related to a specific customer request. Cases are always associated with a contact. When a case is created via API, it may be linked with an external identifier. When a task is queued, an existing case may be associated with the task using the case's external identifier.
\nContact: A customer or individual involved in interactions. When a contact is created via API, it may be linked with an external identifier. When a task is queued, a contact can be associated with the task using the contact's external identifier.
\nThe Task Routing API v1 endpoint prefix is as follows:
\nhttps://<tenant_url>/taskroutingapi/v1/\n\nThis documentation is intended for IT personnel and developers responsible for integrating external systems with Bright Pattern Contact Center. Readers should have some familiarity of REST APIs, JSON data structures, and contact center concepts like services, queues, and dispositions. Experience with scripting or programming is recommended for implementing integrations using this API.
\nThis documentation includes examples for each API method. These examples can serve as a starting point for developing your integrations. You can load these API descriptions into the Postman API Development Environment to interact with the API using your own access tokens.
\nTask Routing requests and responses may carry a JSON-encoded body of type application/json. Successful response bodies differ by method. Failed responses return the following:
{\n\"errorCode\": [integer number],\n\"errorMessage\": \"[string with error description]\"\n}\n\nUsers must be granted the Use Task Routing API privilege in order to use the following API methods. Administrators can grant this privilege in the Contact Center under Roles > Service and Campaign Administration
\nFor more information, refer to the Administration Configuration Guide.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Audience","slug":"audience"},{"content":"Usage","slug":"usage"}],"owner":"31590362","collectionId":"caf4c483-c1ac-4f40-8a71-21d65c560d9e","publishedId":"2sA3XTfLhk","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2024-06-19T22:51:32.000Z"},"item":[{"name":"Authentication","item":[{"name":"Get access token","id":"c3d65020-eece-42ed-88f7-0b7e73244468","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"client_id","value":"String (Username)","type":"text","description":"Username of a BPCC user with the User Privilege Use Task Routing API enabled.
\n"},{"key":"client_secret","value":"String (API Token)","type":"text","description":"The API secret key generated for the user specified by client_id
\n"},{"key":"scope","value":"String (URL)","type":"text","description":"Your tenant URL, e.g., example.brightpattern.com
\n"},{"key":"grant_type","value":"String (\"client_credentials\")","type":"text","description":"Grant type. Must be set to client_credentials.
\n"}]},"url":"https://Returns the access token that must be used to authenticate each subsequent request made via this API.
\n","urlObject":{"protocol":"https","path":["configapi","v2","oauth","token"],"host":["The OAuth 2.0 Client Credentials Grant is used to authenticate clients of this API. The authenticated user is checked for having appropriate privileges to perform the requested operation. The complete list of privileges can be found here. Privileges are assigned to users via one or more Roles.
\nTo obtain an access token:
\nLogin to your BPCC admin portal.
\nNavigate to Users page.
\nSelect or create a user with the privilege Use Taskrouting API.
\nClick the Generate button to generate an API secret key. Copy the generated key and note the username.
\nUse the Get Access Token method to obtain an access token. Set the client_id to the above username and client_secret to the generated API secrect key.
\nUse the value of access_token returned in the response to set the Authorization: Bearer [access token] header of each subsequent request made via the BPCC Task Routing API.
\nQueue a task and associate it with a case and contact.
\nOptionally, you may provide external IDs to associate with the task, case, or contact to prevent duplicates. When external IDs are provided:
\nBPCC checks for existing records linked with the provided External IDs for the task, case, or contact.
\nIf a match is found for an External ID, the corresponding existing record in BPCC is used.
\nIf no match is found for an External ID, a new record (task, case, or contact) is created in BPCC and associated with that External ID.
\nFinally, the task (whether found or newly created) is linked to the case and contact entities (whether found or newly created) and queued in the indicated service.
\ncontactInfo Properties:contactInfo.emails Array Element Properties:contactInfo.addresses Array Element Properties:screenpopData Array Element Properties:Use the screenpopData array to define multiple screen pops that will be displayed conditionally based on the agent's client application (Full Agent Desktop or integrated CRM Widget):
If the agent accepts the task in the full Agent Desktop application, only screen pops with type: \"web\" will be displayed. Multiple web screen pops can be shown simultaneously (e.g., in separate tabs or embedded frames, depending on the webScreenpopShowInTab setting).
You can include multiple objects with type web. All defined web screen pops will be attempted. However, the last values for webScreenpopShowInTab and screenpopShowUponAnswer encountered in the array elements are applied to all screen pops.
If the agent accepts the task within a specific CRM widget (e.g., Dynamics, Salesforce, ServiceNow, or Zendesk), the system looks for a screen pop object in the array with a type matching that CRM (e.g., type: \"dynamicscrm\"). If found, only that specific CRM screen pop is displayed within the widget interface. Any web type screen pops in the array are ignored.
If a matching CRM type is not found in the array, the system then looks for a web type screen pop. If a web screen pop exists, it will be displayed only if its webScreenpopShowInTab setting is true (either explicitly set in the object or inherited from the request's top level). If webScreenpopShowInTab is false, the web screen pop cannot be displayed in the widget.
If both the full Agent Desktop and a CRM widget are open, and the screenpopData contains both a matching CRM type and a web type, only the CRM screen pop will be shown when the task is accepted in the widget.
You can include multiple objects corresponding to different CRMs (e.g., one for dynamicscrm, one for salesforce). However, if you include multiple objects with the same CRM type (e.g., two objects with type: \"dynamicscrm\"), only the last object of that specific CRM type in the array will be used.
caseInfo Properties:taskInfo Properties:Removes the queued task specified by the taskId path variable from the queue and sets its disposition to dispositionName. Canceling a task is possible only while the task is still in the service queue or an agent's personal queue.
\nUse the external query parameter to specify whether taskId is an internal or external identifier.
\nNone
\n","urlObject":{"protocol":"https","path":["taskroutingapi","v1","task",":taskid",""],"host":["Indicates whether the taskId specified in the path is an external task ID (from a CRM or other external system) or an internal task ID generated by Bright Pattern Contact Center.
\n","type":"text/plain"},"key":"external","value":"Boolean"}],"variable":[{"description":{"content":"Identifies the task to be canceled, using either its internal or external ID as specified by the external query parameter.
\n","type":"text/plain"},"type":"any","value":"String (task ID)","key":"taskid"}]}},"response":[{"id":"7c39f98d-6eb2-4040-86d2-a86cb497e80a","name":"Cancel Task","originalRequest":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer E9C97B84D0F72C08A1B31916A1646B91618F63F146CC3694CD2523B63F732363","type":"text"}],"body":{"mode":"raw","raw":"{\n \"note\":\"Cancelled per user request\",\n \"dispositionName\":\"Abandoned\"\n}"},"url":{"raw":"https://Cancel all currently queued tasks associated with the service specified by serviceName. The disposition designated by dispositionName and the note specified by note is applied to each canceled task.
\nModify the priority or associated service of the queued task specified by the taskID path variable.
\nUse the external query parameter to specify whether taskId is an internal or external identifier.
\nNone
\n","urlObject":{"protocol":"https","path":["taskroutingapi","v1","task",":taskid"],"host":["Indicates whether the taskId specified in the path is an external task ID (from a CRM or other external system) or an internal task ID generated by Bright Pattern Contact Center.
\n","type":"text/plain"},"key":"external","value":"Boolean"}],"variable":[{"description":{"content":"Identifies the task to be canceled, using either its internal or external ID as specified by the external query parameter.
\n","type":"text/plain"},"type":"any","value":"String (task ID)","key":"taskid"}]}},"response":[{"id":"721f1aa2-2a73-4644-a5c9-ec5cecadf4f7","name":"Update Task","originalRequest":{"method":"PATCH","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer E9C97B84D0F72C08A1B31916A1646B91618F63F146CC3694CD2523B63F732363","type":"text"}],"body":{"mode":"raw","raw":"{\n\t\"priority\": 100,\n\t\"serviceName\": \"TaskService\"\n}\n"},"url":{"raw":"https://Retrieves information about the task specified by the taskId path variable.
\nUse the external query parameter to specify whether taskId is an internal or external identifier.
\nNone
\nIndicates whether the taskId specified in the path is an external task ID (from a CRM or other external system) or an internal task ID generated by Bright Pattern Contact Center.
\n","type":"text/plain"},"key":"external","value":"Boolean"}],"variable":[{"description":{"content":"Identifies the task to be canceled, using either its internal or external ID as specified by the external query parameter.
\n","type":"text/plain"},"type":"any","value":"String (task ID)","key":"taskid"}]}},"response":[{"id":"87e6aa0e-9603-4444-90cd-863a9e85de4d","name":"Query Task","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer E9C97B84D0F72C08A1B31916A1646B91618F63F146CC3694CD2523B63F732363","type":"text"}],"url":{"raw":"https://The following methods allow tasks within Bright Pattern Contact Center to be queued, canceled, updated, and queried.
\n","_postman_id":"4e984958-ecb4-4184-b997-953bbcfb8962"},{"name":"Error Codes","item":[],"id":"a6067369-43ce-4243-ad0e-1fc9f833b102","description":"The Task Routing API can potentially return any of the following error codes.
\n","_postman_id":"a6067369-43ce-4243-ad0e-1fc9f833b102"}],"event":[{"listen":"prerequest","script":{"id":"7af1b467-d52c-450c-93ec-95d7384fe200","type":"text/javascript","exec":["const echoPostRequest = {"," url: \"https://\" + pm.environment.get(\"tenant_url\") + \"/configapi/v2/oauth/token\","," method: 'POST',"," header: {"," 'Accept': '*/*',"," 'Content-Type': 'application/x-www-form-urlencoded',"," },"," body: {"," mode: 'urlencoded',"," urlencoded : ["," { key: 'client_id', value: pm.environment.get(\"client_id\")},"," { key: 'client_secret', value: pm.environment.get(\"client_secret\")},"," { key: 'scope', value: pm.environment.get(\"scope\")},"," { key: 'grant_type', value: \"client_credentials\"},"," ]"," }","};","","var getToken = true;","","if (!pm.environment.get('accessTokenExpiry') || "," !pm.environment.get('currentAccessToken')) {"," console.log('Token or expiry date are missing')","} else if (pm.environment.get('accessTokenExpiry') <= (new Date()).getTime()) {"," console.log('Token is expired')","} else {"," getToken = false;"," console.log('Token and expiry date are all good');","}","","if (getToken === true) {"," pm.sendRequest(echoPostRequest, function (err, res) {"," console.log(err ? err : res.json());"," if (err === null) {"," console.log('Saving the token and expiry date')"," var responseJson = res.json();"," pm.environment.set('currentAccessToken', responseJson.access_token)"," "," var expiryDate = new Date();"," //console.log(\"expiry date: \",expiryDate)"," //console.log(\"expiry seconds: \", responseJson['expires_in'])"," expiryDate.setSeconds(expiryDate.getSeconds() + Number(responseJson['expires_in']));"," //console.log(\"new expiry date: \", expiryDate)"," pm.environment.set('accessTokenExpiry', expiryDate.getTime());",""," }"," });","}"]}},{"listen":"test","script":{"id":"519e558a-fe67-4aeb-9ffb-c7be21c2efbc","type":"text/javascript","exec":[""]}}],"variable":[{"key":"tenant_url","value":"boromir.bugfocus.com"},{"key":"client_id","value":"User01","type":"string"},{"key":"clientSecret","value":"huuw8tbDgk9tX0r6C4rZfpa6kzCHP4oOZmtP7E3DG5d8yaaGC75Ux0Lb7dkngpAg","type":"string"},{"key":"scope","value":"","type":"string"},{"key":"currentAccessToken","value":"","type":"string"},{"key":"accessTokenExpiry","value":"","type":"string"},{"key":"client_credentials","value":"client_credentials"}]}