AdLingo API Developer Guide

version: v2.0.0

If you're a bot platform that's looking to integrate with AdLingo Ads, then you will need to follow this guide. The docs are segmented into 3 different sections. 1) Request Verification 2) Messaging API 3) Message types.

The AdLingo API is a synchronous API. This means that the user chat cannot be sent a message without having sent a prior request. The flow of a request is as follows:

  1. The user from the chat ad sends a message to AdLingo servers
  2. AdLingo servers send the user request formatted for the bot (eg. AdLingo Ads API)
  3. The bot (AdLingo Ads API) responds with messages
  4. AdLingo servers formats response for user chat ad for display

Authorization (Request Verification)

Access Token Generation

The Access Token needs to be generated in AdLingo’s Ads Builder. This token will be sent with the request to correctly identify that the API request is coming from AdLingo. It will be part of the Authorization header in JWT format. They will be signed by AdLingo , and contain the following payload:

{
  "iat": <issued_at_unix_time>,
  "id": <agent_id>
}

Whereas ‘id’ is a string defined by the developer (you) that identifies your conversational assistant in the context of your own platform.

Endpoints

AdLingo will make API requests with this endpoint metadata:

Property Description
Base URL Defined by Technology Partner in Bot Portal. Must be HTTPS.
Method POST
Request Headers Authorization: Bearer <access_token>, the access_token is defined and generated in the above description

The base url will be in the form:

https://my-endpoint.com/v<version_number>/agents/<agent_id>/sessions/<session_id>

Example:

https://my-endpoint.com/v2/agents/bot-name-id-123/sessions/20ae85b5c0904ed69f330c07a5cac936/messages

Token Verification

To verify the token signature, use the public key present here: https://adlingo.com/jwks.json. The key is in the JWKS format, and most standard JWT libraries can verify tokens from JWKs. For more information on token verification, refer to this guide and the Auth0 Backend/API quickstarts.

The following code sample shows how to verify the token in Python3:

bot_name = 'AdLingo API Demo Bot'


def verify_token(token):
  """Verifies the JWT token using the AdLingo hosted public key."""

  jwks = requests.get('https://adlingo.com/jwks.json').json()
  rsa_key = jwt.algorithms.RSAAlgorithm.from_jwk(json.dumps(jwks['keys'][0]))
  decoded = jwt.decode(token, key=rsa_key, algorithms='RS256')
  return decoded.get('id', '') == bot_name
Response Headers

Response headers should allow Origin for CORS. Eg:

If in the request:

Origin: https://integration.adlingo.com

then the response header should be:

Access-Control-Allow-Origin: https://integration.adlingo.com

General Information on API Message Requests

The following information describes the request you can expect from a message request.

There are three different message types you can expect.

  1. text
  2. session start
  3. postback.

The API messages endpoint will have the form: https://my-endpoint.com/v<version_number>/agents/<agent_id>/sessions/<session_id>/messages for all three different message types. The following describes how the POST bodies are formed:

Session Start

When AdLingo initiates a connection to your endpoint.

NOTE: AdLingo will only initiate sessions upon user interaction or to refresh the message cache.

{
    "messageId": "000102030405060708090a0b0c0d0e0f",
    "message": {
        "type": "sessionStart",
        "value": "",
        "timestampCreated": 1577836800.0,
        "channelData": { /* channel data */}
    }
}

Text Message

When a user sends a message by typing.

{
    "messageId": "000102030405060708090a0b0c0d0e0f",
    "message": {
        "type": "freeText",
        "value": "Hello World",
        "timestampCreated": 1577836800.0,
        "channelData": { /* channel data */}
    }
}

Postbacks

To be sent after a user taps on a postback button or Quick reply.

{
    "messageId": "000102030405060708090a0b0c0d0e0f",
    "message": {
        "type": "postback",
        "value": "Hello World",
        "timestampCreated": 1577836800.0,
        "channelData": { /* channel data */}
    }
}

The exchange protocol is via JSON over HTTPS ("Content-Type: application/json" with character type UTF-8).

{
    "messageId": "000102030405060708090a0b0c0d0e0f",
    "message": {
        "type": "freeText",
        "value": "Hello World",
        "timestampCreated": 1577836800.0,
        "channelData": { /* channel data */}
    }
}

The session ID is a randomized number that will be persistent during the lifetime of a user conversation.

Channel Data

With every message sent from the user, we pass along an object of channelData. Expect the following with every request to the bot:

{
  isAdLingoPreview: boolean, // true if served in a test/preview page
  userDevice: 'MOBILE|TABLET|COMPUTER',
  creativeSize: string,
  userTimezone: number, // Offset in hours from UTC
  language: string, // user browser main language
  creativeId: number|null, // DV360 creative ID
  insertionOrderId: number|null, // Campaign Manager IO IDs, only available for live campaigns.
  lineItemId: number|null, // DV360 Line Item ID, only available for live campaigns.
  placementId: number|null, // DV360 Placement ID
  userZipCode: number, // US & CA only. Available if user opted into personalized ads
  userCountry: string
  userState: string,
  customParameters: object // developer defined
}

Example

{
  isAdLingoPreview: false,
  userDevice: 'MOBILE',
  creativeSize: ‘300x250’,
  userTimezone: -8,
  language: ‘en-US’,
  creativeId: null,
  insertionOrderId: null,
  lineItemId: null,
  placementId: null,
  userZipCode: 94105,
  userCountry: 'US',
  userState: 'CA',
  customParameters: {}
}