Yalo Studio

User's Documentation

The present document describes the available queries in Yalo’s DATA API.

❗️

Early Adopter Program

The participant in the early adopter program may use the listed queries; however, some queries will only be available to a certain group of users. For example, Commerce queries will only be available to customers using Yalo’s conversational commerce engine.

Query Request Limit

Synchronous DATA API

  • Support up to 100,000 records per query response
  • The rate limit is 5 calls per minute.
  • Date range limit to 30 days
  • Date range limit to 90 days back over current date

How to get analytics data?

  1. Create or search for a valid API key {token} check readme doc Overview
  2. Consume the querying endpoint with a specific query {{queryName}}
curl --location --request POST 'https://api-ww-us-001.yalochat.com/dp/data-api/v1/private/analytics/querying' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data-raw '{ 
	"queryName": "{{queryName}}", 
  "limit": "{{totalRecordsToReturn}}", 
  "timeZone": "{{timeZone}}", 
  "startDate": "{{dateRangeInit}}", 
  "endDate": "{{dateRangeEEnd}}", 		
  "customFilters": { 				
  		"flow": "{{flowId}}", 				
      "userId": "{{userId}}", 				
      "storeId": "{{storeId}}", 				
      "storefront": "{{storefrontName}}", 				
      "notificationTemplate": "{{notificationTemplate}}", 				
      "lastStatus": "{{lastStatus}}", 				
      "campaignName": "{{campaignName}}" 		
      }}'

{ 
  "data": [{}, {}, ... , {}], 
	"message": "XXXXXXXXXX", 
	"status": 200 
}

List of available queries

Data DomainQuery Name
Commercecommerce_active_stores
Commercecommerce_summary_by_day
Commercecommerce_summary_by_order
Commerce Legacycommerce_legacy_active_stores
Commerce Legacycommerce_legacy_summary_by_day
Commerce Legacycommerce_legacy_summary_by_order
Messagesmessages_by_hour_block
Messagesmessages_by_day
Notificationsnotifications_by_day
Notificationsnotifications_by_user
Campaignscampaigns_by_day
Campaignscampaigns_text
Campaignscampaigns_soft_blocks
Campaignscampaigns_by_user
Usageusage_by_day_new_and_returning_users
Usageusage_by_day_notification_impact
Usageusage_by_user

Bulk Copy feature

The Bulk copy feature is used for larger queries that can only be obtained asynchronously..

This Bulk Copy feature supports the same queries as listed above.

📘

Disclaimer

The first row of the batch file needs to be discarded. Please refer to the query output metrics (check next sections) for the corresponding headers.

Query Request Limit

Asynchronous Bulk Copy feature

  • Supports up to 3 million records per query batch file
  • The rate limit is 5 calls per minute
  • The output is a zipped file
  • Date range limit to 30 days
  • Date range limit to 90 days back over current date

How to get analytics data?

  1. Create or search for a valid API key {token} check readme doc Overview
  2. Consume the querying endpoint with a specific query {{queryName}} please pay attention to the query parameter bulkCopy=true
curl --location --request POST 'https://api-ww-us-001.yalochat.com/dp/data-api/v1/private/analytics/querying?bulkCopy=true' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data-raw '{ 
		"queryName": "{{queryName}}", 
     "timeZone": "{{timeZone}}" , 
     "startDate": "{{dateRangeInit}}", 
     "endDate": "{{dateRangeEEnd}}",
     "customFilters": { 				
       				"flow": "{{flowId}}", 				
              "userId": "{{userId}}", 				
              "storeId": "{{storeId}}", 				
              "storefront": "{{storefrontName}}", 				
              "notificationTemplate": "{{notificationTemplate}}", 				
              "lastStatus": "{{lastStatus}}", 				
              "campaignName": "{{campaignName}}" 		
     }}'

{ 
  "data": {
		"jobId": "XXXXXXX-XXXXX-XXXXXXX-XXXXX-XXXXXXXXXX",
		"fileName": "data_XXXXXXXXXXXXXXXXX_#############.csv.gz",
		"jobCreatedAt": "YYYY-MM-DDTHH:MM:SS.SSSZ"
		},
  "message": "XXXXXXXXXX", 
  "status": 200 
}
  1. Check the bulk copy job status using {jobId}
curl --location --request GET 'https://api-ww-us-001.yalochat.com/dp/data-api/v1/private/analytics/bulk-copy/jobs/{jobId}' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json'


{ 
  "data": [{
    "JobId": "XXXXXXX-XXXXX-XXXXXXX-XXXXX-XXXXXXXXXX",
    "Status": "XXXXXX",
    "StartTime": "YYYY-MM-DDTHH:MM:SS.SSSZ",
    "EndTime": "YYYY-MM-DDTHH:MM:SS.SSSZ",
    "FileName": "data_XXXXXXXXXXXXXXXXX_#############.csv.gz",
    "HasError": false | true,
    "ErrorMessage": null | "XXXXXXXXX",
    "TotalBytesProcessed": ##########,
    "TotalBytesCompressed": ##########,
    "TotalSlotMS": ######,
    "CreatedAt": "YYYY-MM-DDTHH:MM:SS.SSSZ",
    "UpdatedAt": "YYYY-MM-DDTHH:MM:SS.SSSZ"
  }], 
  "message": "XXXXXXXXXX", 
  "status": 200 
}

🚧

Repeat the step 3 until the status is DONE

  1. When job status is DONE the file is ready to download
curl --location --request GET 'https://api-ww-us-001.yalochat.com/dp/data-api/v1/private/analytics/bulk-copy/jobs/download-file/{jobId}' \
--header 'Authorization: Bearer {tomen}' \
--header 'Content-Type: application/json' \
--output {fileName}

{ 
  "data": [{}, {}, ... , {}], 
  "message": "XXXXXXXXXX", 
  "status": 200 
}

📘

Keep in mind that the file is compressed as *.csv.gz

📘

When a request fails the file will contain an error description and it will not be compressed

🚧

All files persist only for 24 hours