Medical messaging API

Patient ↔ provider messaging for the medical channel only. Your portal keeps customer/support questions on your side; treatment questions come to Bespoke over this API (not an iframe).

Overview

• One message thread per consultation
• You post messages from your website/app with consult + patient identifiers
• Assigned prescribers (and Bespoke staff) read and reply in Bespoke’s Message center
• Replies are pushed back to your callback URL
• Full history stays on the consult as part of the medical record

Enablement

If messaging is disabled, POST/GET …/messages returns 403 messaging_disabled.

Flow

1. Patient asks a treatment question in your app.
2. Your backend POSTs to Bespoke with visit id / external_visit_id and the message.
3. Message appears on that consult’s Message center for the assigned provider.
4. Provider replies in Bespoke.
5. You receive medical_message.created and show the reply in your UI.

Endpoints

GET  https://n-kumar.bespoke-consults.designingit.co/v1/visits/{visit_id_or_external_ref}/messages
POST https://n-kumar.bespoke-consults.designingit.co/v1/visits/{visit_id_or_external_ref}/messages

Same auth headers as the rest of the API: X-Api-Key, X-Api-Secret.

Post a message (partner → Bespoke)

curl -X POST "https://n-kumar.bespoke-consults.designingit.co/v1/visits/javier-consult-1001/messages" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Patient asks about injection site redness after week 2.",
    "external_message_id": "msg-7781",
    "sender_type": "patient",
    "sent_at": "2026-08-30T15:04:00Z",
    "metadata": { "source": "patient_app" }
  }'

Response 201:

{
  "message_id": "…",
  "external_message_id": "msg-7781",
  "direction": "inbound",
  "sender_type": "patient",
  "sender_name": "Patient",
  "body": "Patient asks about injection site redness after week 2.",
  "sent_at": "2026-08-30T15:04:00+00:00",
  "metadata": { "source": "patient_app" },
  "created_at": "…"
}

List the thread

curl "https://n-kumar.bespoke-consults.designingit.co/v1/visits/javier-consult-1001/messages" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Accept: application/json"

{
  "visit_id": "…",
  "external_visit_id": "javier-consult-1001",
  "messages": [ /* chronological */ ]
}

Provider reply → your webhook

When a provider replies in Bespoke, we store an outbound message and — if webhooks are enabled — POST:

{
  "id": "delivery-uuid",
  "event": "medical_message.created",
  "occurred_at": "…",
  "partner_id": "…",
  "data": {
    "message_id": "…",
    "direction": "outbound",
    "sender_type": "prescriber",
    "sender_name": "Alan Reyes",
    "body": "Apply a cool compress and message us if it worsens.",
    "sent_at": "…",
    "visit_id": "…",
    "external_visit_id": "javier-consult-1001",
    "patient_id": "…",
    "external_patient_id": "javier-pt-55",
    "practitioner_id": "…",
    "external_practitioner_id": "dr-42"
  }
}

Signatures, retries, and auth are the same as other partner callbacks — see webhook documentation.

Medical record

• Messages are permanent rows linked to the consultation (and patient).
• Visible in admin and prescriber consultation Message center.
• Not sent to the pharmacy network.

Integration checklist

1. Ask Bespoke to enable medical messaging on your account.
2. Enable webhooks and subscribe to medical_message.created.
3. Always send external_visit_id (and patient refs) when creating consults so threads match.
4. Use external_message_id for safe retries from your app.
5. Render inbound replies from the webhook (or poll GET …/messages as backup).

← API reference Webhooks →