AdLingo API Message Requests

version: v2.0.0

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

There are three different message types you can expect.

  1. Session start
  2. Free text
  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 */}
    }
}

Anatomy of the request object

Property Description
messageId UUID of messageRequest.
message Object that contains the body of the message. The required keys are type, value, channelData, and timestampCreated.
message.type One of sessionStart, freeText or postback
message.value The text data sent by the user.
message.channelData Explained more below.
message.timestampCreated Time of message sent in seconds (float).

Free Text

When a user sends a message by typing.

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

Postback

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 (UUID) 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: {}
}