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

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

📘

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>"
}

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"
}

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"
}

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"
}

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

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"
}

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

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"
}

Response

Success

• Return code: 200
  • OK
• Response body:

{
  "response": "success",
  "message": null,
  "errorCode": "",
  "requestId": "329f83c4-38ca-4760-a18a-3fb44962c536"
}

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"
}

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"
}

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"
}