Data Query API

Overview

The IntelePeer data API is a helper service to retrieve call, message, and application data. The file that you get back from the query contains the dataset you requested. There are a few steps to get to that file — we’ll show you how — but once you’ve got it, the file can aid in:

  • general troubleshooting
  • streamlining your processes
  • analyzing customer behavior and experience
  • creating new solutions to serve your customers
  • fine-tuning existing SmartFlows to your customer experience
 
The Sequence
  1. The GET or HEAD requests on the Q path retrieves and returns available fields via the API. 
  2. Design a query using the fields returned from step 1. 
  3. Submits a request using the POST method on the Q path with the query in the body of the request. A GUID is returned and used for reference in future calls.
    •  Limit results to a specific session using the scope command.
    • A session is a concept of an interaction with SmartFlows, e.g. flow execution.
  4. The query runs. 
  5. Check query status using a GET call on the Q/{guid}/status path. 
  6. Once the query has a complete status, use a GET or HEAD call based on the Q/{guid} path to retrieve the file.
Return Available Fields

Use a GET or HEAD request on the Q path. It returns is JSON file which identifies the fields available for filtering and report shaping.

(negotiable)

{

  "adr": [ "field1", "field2", "field3" ‘],

  "cdr": [ "field2", "field8”, "name”],

  //etc

}
Fields Available to Return
 
Core/Common Fields

ADR.ApplicationRegion

String

ADR.CustomerId

String

ADR.EventName

String

String

ADR.EventSku String

may not be populated

ADR.EventVersion

Integer

1

ADR.FlowId

String

ADR.FlowName

String

ADR.IsTriggerVerb

Boolean

ADR.Originator

String

Engage

ADR.OriginatorId

String

{{ Engage’s ID }}

ADR.SessionId

String

ADR.TimeStamp

ISO8601 Datetime

unix timestamp of ADR creation time

ADR.TransactionId

String

ADR.VerbId

String

ADR.VerbName

String


Optional Fields (depends on event type)

Event Types

CallAnswerIndicator

String ib/ob

Call

CallAnswerTime

ISO8601 Datetime ib/ob

Call

CallDisconnectInitiator

Integer ib/ob

Call

CallDisconnectReason

String ib/ob

Call

CallDuration

Integer ib/ob (what granularity?)

Call

CalledNumber

String ib/ob

Call

CalledNumberCountry

String ib/ob

Call

CalledNumberRegion

String ib/ob

Call

CalledNumberState

String ib/ob

Call

CallEndTime

ISO8601 Datetime ib/ob

Call

CallingNumber

String ib/ob

Call

CallingNumberCity

String ib/ob

Call

CallingNumberCountry

String ib/ob

Call

CallingNumberRegion

String ib/ob

Call

CallingNumberState

String ib/ob, US only

Call

CallOfferTime

ISO8601 Datetime ib/ob

Call

CallVoicemailDetected

Boolean ob only

Call

Channel

String sms,whatsapp,etc

Message

FileReference

String url

Message

FileReferenceType

String MIME type

Message

IsOutboundFromCust Boolean

Call, Message

NetworkFragments

Integer # PDUs (applies to SMS only)

Message

RawMessageSize

Integer bytes

Message

ReceiveTnType

String

Message

SendingCity

String US only

Message

SendingCountry

String

Message

SendingId

String

Message

SendingRegion

String

Message

SendingState

String

Message

SendTnType

String SC, 

Message

SentCity

String

Message

SentCountry

String

Message

SentId

String

Message

SentRegion

String

Message

SentState String US only

Message

NumberOfCharacters

integer ib/ob

SpeachRec

SentimentScore

String ib/ob

SpeachRec

TonalityScore

String ib/ob

SpeachRec

Language

String

SpeachRec

SpeechRecEngine

String

SpeachRec

Confidence Float

SpeachRec

Runtime

ISO8601 Duration

SpeachRec

returncode

String?

SpeachRec

StartTime

ISO8601 Datetime

ApplicationExit

EndTime ISO8601 Datetime

ApplicationExit

Path

String

ApplicationExit

ExitReason

String

ApplicationExit

Request Against Designed Query

Next, use a POST method to set your scope and data filters for the query you designed above. The query accepts a JSON body and a scope filter or data filter, or both, and a format.

Note: At least one filter must be provided.

 
Data
  • data.fields  are optional and a list of fields to be returned for the filtered records.
  • data.filters are an object of JSON filters similar to a MongoDB query which filter the data that is returned.

Notes:

    •  If a scope filter was not provided, data.filters is applied to all records and only matching data is returned.
    •  If a scope filter was provided, data.filters only applies to the subset of records which match the scope, e.g. adr.sid = ‘2fa4d23c95eb411d’, and further constrains the results returned.
 
Scope
  • scope.filters are an object of JSON filters, similar to a MongoDB query, which filter the scope records from which to collect the scope values.
  • scope.field are static: “sid” and identify the scoping field, currently restricted to “sid, whose values are identified by scope.filters, and narrow the overall scope of records.

Note:  Support for an App ID scope is under review. 

Format
  • Format is a JSON object or a string indicating the output format of the data.

Note:  Support for CSV, XML, and SOAP is under review.

request all records related to certain sessions (minimum scope request)

{

  "scope": {

    "field": "sid",

    "filters": {

      "adr.created": { "$gte": "2019-06-15T00:00:000Z" }

    }

  }

}




request all records that explicitly matches criteria (minimum data request)

{

  "data": {

    "filters": {

      "mdr.delivered": { "$gte": "2019-06-15T00:00:000Z", "$lte": "2019-06-15T12:00:000Z" }

    }

  }

}




request all records that match overall session constraints and match data-specific criteria (combined request)

Note that ADR is used to identify applicable sessions, but only associated MDR records will be returned

{

  "data": {

    "filters": {

      "mdr.delivered": { "$gte": "2019-06-15T00:00:000Z", "$lte": "2019-06-15T12:00:000Z" }

    }

  },

  "scope": {

    "field": "sid",

    "filters": {

      "adr.created": { "$gte": "2019-06-15T00:00:000Z" }

    }

  }

}
{ "guid": "cb141a80-39e1-46ad-954c-a70e5c0d08d6" }
Get Status Updates

The GET call provides report status, including an error if applicable. Available updates are:

  • Cancelled
  • Complete
  • Pending
  • Failed

Parameters:

  • Path: Q/{guid}/status
  • Guid:  URL parameter specifying the desired document
GET Q/cb141a80-39e1-46ad-954c-a70e5c0d08d6/status
{

    "guid": "cb141a80-39e1-46ad-954c-a70e5c0d08d6",

    "status": "FAILED",

    "messages": [ "Query range to wide", "All data.fields have empty values, advise adding core fields" ]

}
Get the File

HEAD 

The HEAD call provides headers, such as:

  • Content-Length
  • Content-Type
  • Expires

Parameters:

  • HEAD    Q/{guid}   
  • guid: URL parameter specifying the desired document
HEAD Q/cb141a80-39e1-46ad-954c-a70e5c0d08d6
Content-Length: 543799

Content-Type: application/json

Expires: 2019-08-01T00:00:000Z
GET

The GET call provides the requested document if it hasn’t expired and supports range header so downloads resume.

Parameters:   

  • GET Q/{guid}   
  • guid: URL parameter specifying the desired document
GET Q/cb141a80-39e1-46ad-954c-a70e5c0d08d6
{the data/file}