Ricky logorickyDocs

Get the conversations report

GET
/reports/conversations

Customers who wrote in the period, new or returning, per channel, day and hour. Days and hours are America/Panama time, like the Reports pages; each number is compared with the previous period of the same length.

Scope: reports:read.

Authorization

bearerAuth
headerAuthorizationBearer <token>

An organization API key, rky_live_…, created in Settings → API. Send it only from a server.

Query Parameters

from?string

First day, YYYY-MM-DD, America/Panama, inclusive. Send it with to; without both, the report covers the last 7 days including today.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
Formatdate
to?string

Last day, YYYY-MM-DD, America/Panama, inclusive. A day after today counts as today. The period is at most 366 days.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
Formatdate
channel?string

Only this channel.

Default"all"
Value in"all""whatsapp""instagram""messenger"

Response Body

Success.

application/json
  1. response
data*

How many customers write, whether they are new, and when. Only messages customers send count: a customer is a conversation with at least one of them in the period, and it is new when its first message ever falls in the period. Messages from the team, AI agents or campaigns and conversation openings and closes play no part.

curl -X GET 'https://getricky.ai/api/v1/reports/conversations'
{  "data": {    "period": {      "from": "2026-10-14",      "to": "2026-10-14",      "days": 1,      "granularity": "day",      "time_zone": "America/Panama",      "previous_from": "2026-10-14",      "previous_to": "2026-10-14"    },    "channel": "all",    "totals": {      "customers": 0,      "new_customers": 0,      "returning_customers": 0,      "messages": 0    },    "previous": {      "customers": 0,      "new_customers": 0,      "returning_customers": 0,      "messages": 0    },    "by_channel": [      {        "channel": "whatsapp",        "customers": 0,        "new_customers": 0,        "returning_customers": 0,        "messages": 0      }    ],    "series": [      {        "slot": "2026-10-14",        "new_customers": 0,        "returning_customers": 0,        "previous_customers": 0      }    ],    "heatmap": [      {        "day_of_week": 0,        "hour": 0,        "messages": 0      }    ],    "generated_at": "2026-10-14T15:30:00.000Z"  }}