Ricky logorickyDocs

List the conversations ads brought

GET
/ads/conversations

Each conversation a Meta ad opened or brought back in the period, newest first, with the ad, the contact, the conversation's state and the replies it got. Read from the customer messages Ricky received, so it works without connecting Meta Ads; the ad's name, campaign and ad set (ad_referral.resolved) need the connection. The period is America/Panama days, as in GET /reports/ads, whose per-ad conversations these rows add up to.

Scope: conversations: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
ad_id?string

Only this Meta ad.

Match^\d+$
Lengthlength <= 32
campaign_id?string

Only ads of this Meta campaign, among the ads Ricky synced from a connected ad account.

Match^\d+$
Lengthlength <= 32
ad_set_id?string

Only ads of this Meta ad set, among the ads Ricky synced from a connected ad account.

Match^\d+$
Lengthlength <= 32
channel?string

Only conversations on this channel.

Value in"whatsapp""instagram""messenger"
page_size?integer

Items per page.

Range1 <= value <= 100
Default50
cursor?string

next_cursor from the previous page. Use it unchanged.

Lengthlength <= 2048

Response Body

Success.

application/json
  1. response
data*array<>
next_cursor*|

Pass as cursor for the next page; null on the last page.

curl -X GET 'https://getricky.ai/api/v1/ads/conversations'
{  "data": [    {      "ad_referral": {        "ad_id": "120210000000000001",        "channel": "whatsapp",        "message_id": "c41d7e2a-5b6f-4a89-8c3d-0e1f2a3b4c5d",        "conversation_id": "9b2e4c61-7a3f-4d18-b5c2-6e0f1a2b3c4d",        "contact_id": "3f6c2b1e-8d4a-4b7e-9a51-2c7d8e9f0a1b",        "referred_at": "2026-10-14T15:30:00.000Z",        "source_type": "ad",        "source_url": "https://fb.me/2ZBx1WlQe",        "headline": "Implantes dentales en un día",        "body": "Agenda tu evaluación sin costo.",        "media_type": "video",        "image_url": null,        "video_url": null,        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a",        "ref": null,        "resolved": {          "ad_name": "Implantes - video octubre",          "campaign_id": "120210000000000003",          "campaign_name": "Implantes dentales",          "ad_set_id": "120210000000000002",          "ad_set_name": "Panamá 30-55",          "ad_account_id": "1234567890",          "synced_at": "2026-10-14T15:30:00.000Z"        }      },      "opened_conversation": true,      "message_text": "Hola, quiero más información sobre los implantes.",      "contact": {        "id": "3f6c2b1e-8d4a-4b7e-9a51-2c7d8e9f0a1b",        "name": "Ana Pérez",        "phone": "+50760001234",        "external_id": "50760001234"      },      "conversation": {        "id": "9b2e4c61-7a3f-4d18-b5c2-6e0f1a2b3c4d",        "status": "open",        "close_category": "resolved",        "closed_at": "2026-10-14T15:30:00.000Z",        "created_at": "2026-10-14T15:30:00.000Z"      },      "customer_messages": 0,      "replies": 0,      "first_reply_seconds": 0    }  ],  "next_cursor": "string"}

Get Meta ads insights GET

Spend, delivery and Meta's actions for the connected ad accounts over a period, per account, campaign, ad set or ad, computed live by Meta. Answers `rule_violation` when the organization has not connected Meta Ads, and `forbidden` when Meta no longer accepts its connection. Scope: `reports:read`.

Get Google Ads campaign results GET

Live Google Ads campaign metrics and attributed WhatsApp conversations for advertiser accounts selected by the organization. Scope: `reports:read`.