Channels

Path parameters

None.

Query parameters

None.Serves a fixed document and takes no input at all.

Body parameters

None.GET requests carry no body.

Response

Status codes

curl

curl -X GET 'https://api.oprag.ai/widget.js' \
  -H 'X-Oprag-Key: sk_live_...'

Before you call it

• Only served while the project is live or indexing and its widget is enabled.
• Returns displayName, welcomeMessage, and theme (primaryColor, position, and an optional mode).
• theme.mode is auto, light, or dark. auto follows the visitor's prefers-color-scheme.
• quickPrompts and the lead-capture fields appear only when those features are on, avatarUrl, launcherIconUrl, ctaChips, and proactiveTriggers only when set on the widget config, and escalationEnabled only when the project has an escalation webhook or email.
• proactiveTriggers drive the widget's teaser bubbles. The widget shows at most one teaser per session, and suppresses all teasers for 7 days after a visitor dismisses one.
• visitorContextEnabled is a project-level master switch, distinct from the widget's per-visitor consent banner (window.oprag.setConsent() / handle.setConsent()). Omitted or true (the default) leaves visitor-context capture and the consent banner on; false disables both for every visitor on the project.

Path parameters

Query parameters

None.Reads the resource named in the path; there is nothing else to select.

Body parameters

None.GET requests carry no body.

Response

{
  "displayName": "Acme Support",
  "welcomeMessage": "Hi! Ask me anything about our product.",
  "quickPrompts": ["What is your refund policy?"],
  "avatarUrl": "https://cdn.acme.com/bot-avatar.png",
  "launcherIconUrl": "https://cdn.acme.com/launcher-icon.svg",
  "ctaChips": [
    { "label": "Book a demo", "url": "https://acme.com/demo" },
    { "label": "Email us", "url": "mailto:hello@acme.com" }
  ],
  "proactiveTriggers": [
    {
      "message": "Questions about pricing? I can help!",
      "trigger": "delay",
      "value": 30,
      "pagePattern": "/pricing*"
    }
  ],
  "feedbackEnabled": true,
  "visitorContextEnabled": true,
  "escalationEnabled": false,
  "theme": {
    "primaryColor": "#2563eb",
    "position": "bottom-right",
    "mode": "auto"
  }
}

Status codes

curl

curl -X GET 'https://api.oprag.ai/v1/widget/{projectId}/config' \
  -H 'X-Oprag-Key: sk_live_...'

Before you call it

• This is what powers the widget's transcript restore: the widget persists conversationId and visitorId locally and replays the thread when the visitor comes back.
• messages is chronological (oldest first), capped at the most recent 50.
• Each message carries role (user or assistant), text, and createdAt. sources appears only when the stored answer cited documents, and each entry carries documentTitle only — no excerpts, locations, or scores on this channel.
• The 404 is deliberately indistinguishable: a missing conversation, a conversation from another project, and a visitorId mismatch all answer identically, so conversation ids cannot be probed.

Path parameters

Query parameters

Body parameters

None.GET requests carry no body.

Response

{
  "messages": [
    {
      "role": "user",
      "text": "What is your refund policy?",
      "createdAt": "2026-08-27T09:14:03.000Z"
    },
    {
      "role": "assistant",
      "text": "Refunds are available within 30 days of purchase.",
      "createdAt": "2026-08-27T09:14:07.000Z",
      "sources": [{ "documentTitle": "Refund policy" }]
    }
  ]
}

Status codes

curl

curl -X GET 'https://api.oprag.ai/v1/widget/{projectId}/conversations/{conversationId}/messages' \
  -H 'X-Oprag-Key: sk_live_...'

Before you call it

• Meta calls this when you register the webhook; your code never does.
• hub.verify_token is compared against the global WHATSAPP_VERIFY_TOKEN, never a per-project value.

Path parameters

None.

Query parameters

Body parameters

None.GET requests carry no body.

Response

1234567890

Status codes

curl

curl -X GET 'https://api.oprag.ai/v1/webhooks/whatsapp' \
  -H 'X-Oprag-Key: sk_live_...'

Before you call it

• Meta calls this, not your code. It needs an X-Hub-Signature-256 header — sha256= followed by an HMAC-SHA256 of the raw body under the app secret — and the raw JSON body.
• Text messages only. Deliveries are de-duplicated on Meta's message id, and phone_number_id selects which project answers.
• Answers run through the shared chat pipeline with channel: "whatsapp".
• An unmapped or disabled connection is acknowledged without running chat at all, so Meta stops retrying.

Path parameters

None.

Query parameters

None.The provider signs and posts the whole payload; nothing is read from the URL.

Body parameters

Defined by the caller.Inbound message payload from WhatsApp.

Response

Status codes

curl

curl -X POST 'https://api.oprag.ai/v1/webhooks/whatsapp' \
  -H 'X-Oprag-Key: sk_live_...'

Path parameters

Query parameters

None.Reads the resource named in the path; there is nothing else to select.

Body parameters

None.GET requests carry no body.

Response

Status codes

curl

curl -X GET 'https://api.oprag.ai/v1/projects/{projectId}/widget-config' \
  -H 'Authorization: Bearer <Cognito JWT>'

Before you call it

• Branding URLs — avatarUrl, launcherIconUrl, and each chip's url — must be https://, up to 2048 characters; chip URLs may also be mailto:. URLs carrying credentials, a raw IP address, or a localhost host are rejected with 400.
• ctaChips labels are limited to 40 characters. At most 3 chips are kept, at most 3 proactiveTriggers, and at most 6 quickPrompts; overflow is dropped silently, not rejected.
• Each proactive trigger fires its message as a teaser on the visitor's page. trigger: "delay" needs value in whole seconds (5–600), trigger: "scroll" needs value in whole percent (10–90), and trigger: "exit" (exit intent) must omit value. An optional pagePattern — starting with /, up to 200 characters, with one optional trailing * wildcard — limits which pages it fires on.
• An empty string clears avatarUrl or launcherIconUrl; an empty array clears ctaChips, quickPrompts, or proactiveTriggers.
• feedbackEnabled and visitorContextEnabled both default to true when omitted. visitorContextEnabled: false is a project-level kill switch: it turns off visitor-context capture (referrer, landing page, UTM) and the widget's per-visitor consent banner for every visitor, overriding any visitor's own consent choice — see GET /v1/widget/{projectId}/config.

Path parameters

Query parameters

None.Everything it needs is in the request body.

Body parameters

Request

{
  "displayName": "Acme Support",
  "avatarUrl": "https://cdn.acme.com/bot-avatar.png",
  "launcherIconUrl": "https://cdn.acme.com/launcher-icon.svg",
  "ctaChips": [
    { "label": "Book a demo", "url": "https://acme.com/demo" },
    { "label": "Email us", "url": "mailto:hello@acme.com" }
  ],
  "proactiveTriggers": [
    {
      "message": "Questions about pricing? I can help!",
      "trigger": "delay",
      "value": 30,
      "pagePattern": "/pricing*"
    }
  ]
}

Response

{
  "companyId": "co_abc123",
  "projectId": "proj_abc123",
  "enabled": true,
  "displayName": "Acme Support",
  "welcomeMessage": "How can I help?",
  "avatarUrl": "https://cdn.acme.com/bot-avatar.png",
  "launcherIconUrl": "https://cdn.acme.com/launcher-icon.svg",
  "ctaChips": [
    { "label": "Book a demo", "url": "https://acme.com/demo" },
    { "label": "Email us", "url": "mailto:hello@acme.com" }
  ],
  "proactiveTriggers": [
    {
      "message": "Questions about pricing? I can help!",
      "trigger": "delay",
      "value": 30,
      "pagePattern": "/pricing*"
    }
  ],
  "theme": {
    "primaryColor": "#5046e5",
    "position": "bottom-right"
  },
  "createdAt": "2026-08-11T12:00:00.000Z",
  "updatedAt": "2026-08-28T12:00:00.000Z",
  "scriptTag": "<script src=\"https://api.dev.oprag.ai/widget.js\" data-project=\"proj_abc123\" data-embed-key=\"YOUR_EMBED_KEY\"></script>"
}

Status codes

curl

curl -X PATCH 'https://api.oprag.ai/v1/projects/{projectId}/widget-config' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{"displayName": "Acme Support","avatarUrl": "https://cdn.acme.com/bot-avatar.png","launcherIconUrl": "https://cdn.acme.com/launcher-icon.svg","ctaChips": [{ "label": "Book a demo", "url": "https://acme.com/demo" },{ "label": "Email us", "url": "mailto:hello@acme.com" }],"proactiveTriggers": [{"message": "Questions about pricing? I can help!","trigger": "delay","value": 30,"pagePattern": "/pricing*"}]}'

Before you call it

• status is disconnected, connected, or error. Before the first connection, connected and enabled are both false and status is disconnected.
• No secrets are returned — this is a WhatsAppChannelStatus, in which tokenConfigured and webhookVerifyConfigured report only whether they exist.

Path parameters

Query parameters

None.Reads the resource named in the path; there is nothing else to select.

Body parameters

None.GET requests carry no body.

Response

{
  "connected": true,
  "enabled": true,
  "phoneNumberId": "123456789",
  "displayPhoneNumber": "+15551234567",
  "wabaId": "987654321",
  "tokenConfigured": true,
  "webhookVerifyConfigured": true,
  "lastInboundAt": "2026-08-11T12:00:00.000Z",
  "status": "connected"
}

Status codes

curl

curl -X GET 'https://api.oprag.ai/v1/projects/{projectId}/channels/whatsapp' \
  -H 'Authorization: Bearer <Cognito JWT>'

Before you call it

• Ownership of the number is verified against the Meta Graph API with the supplied token before anything is stored.
• accessToken is encrypted at rest, which requires CHANNEL_TOKEN_ENCRYPTION_KEY to be configured.
• Hub webhook verification always uses the global WHATSAPP_VERIFY_TOKEN, never a per-project one.
• A successful connect returns the project's WhatsAppChannelStatus, exactly as GET …/channels/whatsapp would.

Path parameters

Query parameters

None.Everything it needs is in the request body.

Body parameters

Request

{
  "phoneNumberId": "123456789",
  "wabaId": "987654321",
  "accessToken": "EAA...",
  "displayPhoneNumber": "+15551234567"
}

Response

{
  "connected": true,
  "enabled": true,
  "phoneNumberId": "123456789",
  "displayPhoneNumber": "+15551234567",
  "wabaId": "987654321",
  "tokenConfigured": true,
  "webhookVerifyConfigured": true,
  "status": "connected"
}

Status codes

curl

curl -X POST 'https://api.oprag.ai/v1/projects/{projectId}/channels/whatsapp/connect' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{"phoneNumberId": "123456789","wabaId": "987654321","accessToken": "EAA...","displayPhoneNumber": "+15551234567"}'

Before you call it

• Returns the project's WhatsAppChannelStatus with the new enabled value.

Path parameters

Query parameters

None.Everything it needs is in the request body.

Body parameters

Request

{ "enabled": false }

Response

{
  "connected": true,
  "enabled": false,
  "phoneNumberId": "123456789",
  "displayPhoneNumber": "+15551234567",
  "wabaId": "987654321",
  "tokenConfigured": true,
  "webhookVerifyConfigured": true,
  "status": "connected"
}

Status codes

curl

curl -X PATCH 'https://api.oprag.ai/v1/projects/{projectId}/channels/whatsapp' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{ "enabled": false }'

Before you call it

• Deletes both the connection row and the global phone_number_id lookup.

Path parameters

Query parameters

None.Acts on the resource named in the path; there is nothing to choose.

Body parameters

None.DELETE requests carry no body.

Response

Status codes

curl

curl -X DELETE 'https://api.oprag.ai/v1/projects/{projectId}/channels/whatsapp' \
  -H 'Authorization: Bearer <Cognito JWT>'