Service Guide
ENGAGE® Federated Batch Push Service Guide
Prerequisites
Before using the Federated Batch Push Service, the following items must be configured in the Branded Communication Content Portal.
Assets – graphics that display on a device during an incoming call
Program Content – associated content that will be displayed on a mobile device when a call is received
aNumbers – any originating or outgoing numbers used for calling that must be configured in the Content Portal before any branded communication content may be delivered
U.S. Base URL
International Base URL
Open Endpoints
Open endpoints do not require authentication.
Get Token
POST
/federated/content/v2/token
Endpoints Requiring Authentication
Endpoints for checking the health of previously granted Access Token:
Check Token Health
GET
/federated/content/v2/token/health
Endpoints for Batch pushing ENGAGE content to enabled devices:
Push ENGAGE Content
POST
/federated/outbound/v2/batch
Endpoint Details
Get Token
Get Token returns an access token to be used as Authorization header for all Metrics service requests. This request should be the prerequisite for subsequent service requests.
Tokens are valid for 15 minutes. When the token expires, it should be refreshed using the Get Token endpoint
Prerequisities
Client ID & Client Secret : generated and delivered to integration customers by First Orion
Request
URL
/federated/content/v2/token
Method
POST
Headers
- Content-type: application/json
- X-Federated-Purpose: inform
Body
{
"clientId": "<clientId>",
"clientSecret": "<clientSecret>"
}
Field | Type | Required | Description |
---|---|---|---|
clientId | String | Yes | Federal client identifier provided |
clientSecret | String | Yes | Secret code for federated client provided by First Orion and used in the request to retrieve a valid Access Token Recommendation: Protect this value in the same manner as a password |
Response
Success
- Return code: 200 OK
- Response body:
{
"accessToken": "eyJraWQiOiJzVkM5eXczZ2Vtckwzb2ZpbXZCM1BSWGNWc1JhcXJsR0lQSWN0TDhUcXBrPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJrdjQ4NmhxYWxsYml2c2t2NnE2M3Zhc2NwIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJjb20uZmlyc3Rvcmlvbi5lbmdhZ2UuZmVkZXJhdGlvblwvZmVkZXJhdGVkaW5mb3JtIiwiYXV0aF90aW1lIjoxNTYwMzUyNDc1LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAudXMtZWFzdC0xLmFtYXpvbmF3cy5jb21cL3VzLWVhc3QtMV80WlZGZDBKbXEiLCJleHAiOjE1NjAzNTYwNzUsImlhdCI6MTU2MDM1MjQ3NSwidmVyc2lvbiI6MiwianRpIjoiNzRiZTczOTktZTZmYi00Njk4LWIwMzUtMjdkMzE0YTI4MTdmIiwiY2xpZW50X2lkIjoia3Y0ODZocWFsbGJpdnNrdjZxNjN2YXNjcCJ9.Od3JH7qUV15B7LisXP6oj6elwRn8omZJJbmtWu-X9tVHN9P846nVRQSaWyOqt6a91afdkd5sM7Hs4UoNeWqcIvAio93lAesSEEYxDQrHsi4LpxQ_Fb4nF_9Mk_kPrgfnqmSdRzWhRrkdLhuvrAvbFL6wm14TSKeHX-mYVBe4LqnYA8Ok297YYSVLgBk4lUw1Vb2brUWwpT71ddLE0nUE7rNL69HE1qX9N5zc3uzpsVdU8IqscyZFbwZOCfRaTX7MYAtzj9mFxyumYKVRM5lZcn87i4RETjh4pTtj-8I4l3TrNyu4MGO7EpslgmnPvk04liV6s77JMh3fe1Q3wQNzdQ",
"message": "Success",
"errorCode": 0,
"requestId": "12ab005b-1522-406b-82c9-a2ab9a1ff49d"
}
Field | Type | Description |
---|---|---|
accessToken | String | Access token used for Authentication in subsequent service requests, i.e., (Authorization: Bearer '') |
message | String | Message returned from server |
errorCode | String | Error code returned from server |
requestId | String | Unique HTTP request made to server |
Error 500 - Failed to grant accessToken error (missing clientId)
- Return code: 500 Internal Server Error
- Response body:
{
"accessToken": null,
"message": "Failed to grant access token",
"errorCode": 500,
"requestId": "5cf3ad7e-0428-491f-a85f-c444487d1523"
}
Field | Type | Description |
---|---|---|
accessToken | String | Null value returned for missing token |
message | String | Message returned from server |
errorCode | String | Error code returned from server |
requestId | String | Unique HTTP request made to server |
Check Token Health
Returns health of access token used as Authentication header. Tokens should be refreshed after the current Token has expired.
A healthy token will return a 200 OK response and token details in the response body
An expired token will return a 401 Unauthorized response and should be refreshed
Prerequisities
The value for the header Authorization: Bearer Token will be returned by the Get Token service request
Request
URL
/federated/content/v2/token/health
Method
GET
Headers
- Content-type: application/json
- Authorization: Bearer Token
Response
Success
- Return code: 200 OK
- Response body:
{
"accessToken": null,
"message": "Healthy",
"errorCode": "",
"requestId": "5c79f9a0-447e-4093-87d8-05bdd25e9200"
}
Field | Type | Description |
---|---|---|
accessToken | String | Access token used for Authentication in subsequent service requests, i.e., (Authorization: Bearer Token) |
message | String | Message returned from server |
errorCode | String | Error code returned from server |
requestId | String | Unique HTTP request made to server |
Error 401 - accessToken invalid or expired error
- Return code: 401 Unauthorized
- Response body: None
ENGAGE Batch Push Content: aNumber List
Delivers content to multiple ENGAGE-enabled devices by providing a list of aNumbers.
Prerequisites
Authorization Token: the value for the header Authorization: Bearer Token will be returned by the Get Token service request
Program Content UUID: the associated ENGAGE Program to be delivered as an enhanced experience to ENGAGE-enabled handsets. Programs are set up and configured in the Content Portal – where the Program Content UUID can be found
Request
URL
/federated/outbound/v2/batch?programContentUuid= {programContentUuid}
Method
POST
Headers
- Authorization: Bearer accessToken from Get Token request;
- Content-type : application/json
Query Parameters
- programContentUuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
- 3e1b9b27-d1f9-4c8d-800f-bb534d6928d6
Field | Tyoe | Required | Desciption |
---|---|---|---|
programContentUuid | String | Yes | UUID associated to an ENGAGE program being delivered to device |
Body – With List of aNumbers
{
"destinations": [
{
"bNumber": "+15018902005",
"personalization": {
"MY_VAR": "Put Custom Text Here"
},
"customTrackingId": "custom-tracking-1"
},
{
"bNumber": "+14258309029",
"personalization": {
"MY_VAR": "Put Custom Text Here"
},
"customTrackingId": "custom-tracking-2"
}
],
"aNumbers": [
"+5014008029",
"+5013509988"
],
"notBefore": "2020-02-10T16:00:00Z",
"ttlSeconds": "3600",
"keepAfterCall": "false"
}
Field | Type | Required | Description |
---|---|---|---|
destinations | Array | Yes | List of objects with bNumbers to push content to devices |
destinations[0].bNumber | String | Yes | Device number that will display program content when a call is received after a successful push Must be E.164 format |
destinations[0].personalization.MY_VAR | String | No | Custom text sent to bNumber and displayed during call Recommended value: 20 First Orion best practice: maximum of 20 characters as messages over 20 characters may not display correctly on all devices |
destinations[0].customTrackingId | String | No | Optional ID for client-side tracking |
aNumbers | Array String | Yes Cannot send aNumber Group ID | Originating numbers calling a bNumber. aNumber must be previously uploaded in the Branded Communication Content Portal List of up to 400 ANumbers in E.164 format Cannot send UUID |
notBefore | DateTime(UTC) | No | Datetime set before sending content to devices |
ttlSeconds | Integer | Yes | Duration, in seconds, for content to live on the device following successful content push Default is 3600 Recommended value: 960 seconds First Orion best practice: set the TTL to 16 minutes |
keepAfterCall | Boolean | No | Set if content should be kept on device after call Default is false Recommended value: false First Orion best practice: do not keep content on the device after a call or successful push |
ENGAGE Batch Push Content: aNumber Group UUID
Delivers content to multiple ENGAGE-enabled devices by providing an aNumber Group UUID – configured and located in the Content Portal.
Prerequisites
Authorization Token: the value for the header Authorization: Bearer Token will be returned by the Get Token service request
Program Content UUID: the associated ENGAGE Program to be delivered as an enhanced experience to ENGAGE-enabled handsets. Programs are set up and configured in the Content Portal – where the Program Content UUID can be found
aNumber Group UUID: pushing content using an aNumber Group UUID configured in the Content Portal. The UUID can be identified in the Outbound Calling Numbers -> Grouping Numbers section
Request
URL
/federated/outbound/v2/batch?programContentUuid={programContentUuid}
Method
POST
Headers
- Authorization: Bearer accessToken from Get Token request
- Content-type : application/json
Query Parameters
- programContentUuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
- 3e1b9b27-d1f9-4c8d-800f-bb534d6928d6
Field | Type | Required | Description |
---|---|---|---|
programContentUuid | String | Yes | UUID associated to ENGAGE program being delivered to device |
Body – aNumber Group
{
"destinations": [
{
"bNumber": "+15018902005",
"personalization": {
"MY_VAR": "Put Custom Text Here"
},
"customTrackingId": "custom-tracking-1"
},
{
"bNumber": "+14258309029",
"personalization": {
"MY_VAR": "Put Custom Text Here"
},
"customTrackingId": "custom-tracking-2"
}
],
"aNumberGroupId": "935b91a0-f2fb-4c43-b629-63fea6634512",
"notBefore": "2020-02-10T16:00:00Z",
"ttlSeconds": "3600",
"keepAfterCall": "false"
}
Field | Type | Required | Description |
---|---|---|---|
destination | Array | Yes | List of objects with bNumbers to push content to devices |
destinations[0].bNumber | String | Yes | Device number that will display program content when a call is received after a successful push Must be E.164 format |
destinations[0].personalization.MY_VAR | String | No | Custom text sent to bNumber and displayed during call Recommended value: 20 First Orion best practice: maximum of 20 characters as messages over 20 characters may not display correctly on all devices |
destinations[0].customTrackingId | String | No | Optional ID for client-side tracking |
aNumbers | Array String | Yes Cannot send aNumber Group ID | Originating numbers calling a bNumber. aNumber must be previously uploaded in the Branded Communication Content Portal List of up to 400 aNumbers in E.164 format Cannot send UUID |
notBefore | DateTime(UTC) | No | Datetime set before sending content to devices |
ttlSeconds | Integer | Yes | Duration, in seconds, for content to live on the device following successful content push Default is 3600 Recommended value: 960 seconds First Orion best practice: set the TTL to 16 minutes |
keepAfterCall | Boolean | No | Set if content should be kept on device after call Default is false Recommended value: false First Orion best practice: do not keep content on the device after a call or successful push |
Response
Success
- Return code: 200
- OK
- Response body:
{
"response": "success",
"message": null,
"errorCode": "",
"requestId": "329f83c4-38ca-4760-a18a-3fb44962c536"
}
Field | Type | Description |
---|---|---|
response | Object | Response object from server |
message | String | Message returned from server |
errorCode | String | Error code returned from server |
requestId | String | Unique HTTP request made to server |
Error 401 - Bearer token used for Authorization header is invalid
- Return code: 401
- Unauthorized
- Response body: None
Response 200 - One or more aNumbers being sent is not associated with the Service Provider making request
- Return code: 200
- OK
- Response body:
{
"response": "Not allowed to use one or more anumbers.",
"message": "Batch push could not complete push successfully.",
"errorCode": 200,
"requestId": "51934465-cc14-4e68-97a0-af7d6faf9f55"
}
Field | Type | Description |
---|---|---|
response | Object | Response object from server |
message | String | Message returned from server |
errorCode | String | Error code returned from server |
requestId | String | Unique HTTP request made to server |
Error 400 - Program used not correctly configured
- Return code: 400
- Unauthorized
- Response body:
{
"response": "Invalid program setup on this program",
"message": "Batch push could not complete push successfully.",
"errorCode": 400,
"requestId": "e9a76f6b-b921-4ffa-b6f2-1a29334073c4"
}
Field | Type | Description |
---|---|---|
response | Object | Response object from server |
message | String | Message returned rom server |
errorCode | String | Error code returned from server |
requestId | String | Unique HTTP request made to server |
Error 400 - Missing aNumber or aNumber GroupID field or field value
- Return code: 400
- Bad Request
- Response body:
{
"response": "Must send aNumbers or a valid ANumberGroupId",
"message": "Batch could not complete push successfully.",
"errorCode": 400,
"requestId": "04707ac5-36e1-42f1-b747-355fad2d772b"
}
Field | Type | Description |
---|---|---|
response | Object | Response object from server |
message | String | Message returned from server |
errorCode | String | Error code returned from server |
requestId | String | Unique HTTP request made to server |
Updated 10 months ago