chatrail-dev Internal API

openapi: 3.2.0
info:
  title: ChatRail Internal API
  version: 1.0.0
  description: 'Send, schedule and receive WhatsApp messages through a linked-device session.


    **Two things the API is careful about, which shape every endpoint below.**


    *Accepted is not delivered.* A 202 means the message is durably stored and queued. Only the `status` field ever claims WhatsApp delivered anything, and `queued`, `submitted`, `sent`, `delivered` and `read` are deliberately distinct.


    *A retry must not send twice.* Send `Idempotency-Key` on every send. A replay returns the original response; a concurrent duplicate is told to retry rather than allowed to race.'
  contact:
    name: ChatRail
    url: https://www.chatrail.dev
servers:
- url: https://www.chatrail.dev
security:
- apiKey: []
tags:
- name: Internal
  description: Called by the transport, not by you.
paths:
  /v1/billing/creem/webhook:
    post:
      summary: Creem webhook
      description: Called by Creem, not by you. Verified against `creem-signature`, a plain HMAC-SHA256 of the exact request body — Creem retries a non-2xx for up to 24 hours, so redeliveries are expected and deduplicated by event id.
      tags:
      - Internal
      operationId: post_v1_billing_creem_webhook
      responses:
        '200':
          description: 'Accepted — `duplicate: true` if this event id was already processed.'
      security: []
  /v1/billing/nowpayments/webhook:
    post:
      summary: NOWPayments payment notification
      description: Called by NOWPayments, not by you. Verified against `x-nowpayments-sig`, an HMAC-SHA512 of the key-sorted JSON body. Repeated notifications are deduplicated by payment id and status.
      tags:
      - Internal
      operationId: post_v1_billing_nowpayments_webhook
      responses:
        '200':
          description: 'Accepted — `duplicate: true` if this notification was already processed.'
      security: []
  /v1/provider/{providerName}/{token}:
    post:
      summary: Provider callback
      description: Called by the WhatsApp transport, not by you. Authenticated by the per-connection token returned once when the connection was created. Redeliveries are deduplicated.
      tags:
      - Internal
      operationId: post_v1_provider__providerName___token_
      parameters:
      - name: providerName
        in: path
        required: true
        schema:
          type: string
        description: Transport name, e.g. `waha`.
      - name: token
        in: path
        required: true
        schema:
          type: string
        description: The connection callback token.
      responses:
        '202':
          description: Handled or ignored.
        '404':
          description: Unknown callback.
      security: []
  /v1/provider/{providerName}/sessions/{sessionId}:
    post:
      summary: Signed provider callback
      description: Called by the WhatsApp transport, not by you. The URL names the session; the body is signed with the connection’s own key (`X-Webhook-Hmac`, HMAC-SHA512 over the exact bytes). Replaces the token URL, which put a credential in every proxy log.
      tags:
      - Internal
      operationId: post_v1_provider__providerName__sessions__sessionId_
      parameters:
      - name: providerName
        in: path
        required: true
        schema:
          type: string
        description: Transport name, e.g. `waha`.
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
        description: The transport’s session name.
      responses:
        '202':
          description: Handled or ignored.
        '404':
          description: Unknown session or bad signature.
      security: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'A workspace API key, `cr_live_…`. Server-side only: it carries workspace authority and must never reach a browser.'
    session:
      type: apiKey
      in: cookie
      name: chatrail_session
      description: Dashboard session cookie. Set by `/v1/auth/verify`.