Service Guide

Call Enhancement Solutions ENGAGE Federated Batch Push Service Guide

Prerequisites

Before using the Federated Batch Push Service, the following items must be configured in the Call Enhancement Content Portal.

  • Assets – graphics displayed on device during an incoming call
  • Program Content – associated content that will be displayed on a mobile device when a call is received
  • aNumbers – originating or outgoing number(s) used for calling that must be configured in the Content Portal before delivering content

U.S. Base URL

https://api.fo-engage.com

International Base URL

https://api.engage-ae.com

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.

Prerequisites

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

Failed to Grant Access Token Error (missing clientId)

  • Return code: 500
    • Internal Server Error
  • Response body:

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 details about the token in the response body
  • An expired token will return a 401 Unauthorized response and should be refreshed

Prerequisites

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":400,
   "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

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 Call Enhancement 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 Call Enhancement 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 secondsFirst 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": 0,
  "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

"aNumbers":["+12138675309"]

  • Return code: 200
    • OK
  • Response body:
{
  "response": "Not allowed to use one or more anumbers.",
  "message": "Batch push could not complete push successfully.",
  "errorCode": 15000,
  "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": 15000,
  "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

"aNumbers":[x]

"aNumberGroupId": ""

  • Return code: 400
    • Bad Request
  • Response body:
{
  "response": "Must send aNumbers or a valid ANumberGroupId",
  "message": "Batch could not complete push successfully.",
  "errorCode": 15000,
  "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


Did this page help you?