Global Clinic ConnectGuides
Integration step 02

Send patient messages

Send a transactional text or approved WhatsApp template while respecting consent, reply windows, and delivery state.

OutcomeA message accepted into the workspace’s delivery flow
Required scopesmessages:send
Step by step

Typical integration workflow

01

Prepare the recipient

Use an international phone number and confirm the workspace is allowed to contact the recipient for this purpose.

02

Choose text or template

Use text only while the reply window is open. Use an approved template when the window is closed or the communication policy requires it.

03

Create an idempotency key

Generate one unique value for the intended message and reuse it only when retrying that exact request.

04

Submit and record identifiers

Store the returned message_id and conversation_id so later synchronization can match the accepted message.

05

Follow delivery separately

Queued means accepted for processing. Read conversation messages to observe provider delivery information when available.

API reference

Endpoint for this capability

These are the supported public contracts for this integration step.

POST/api/public/v1/messages
Scope · messages:send

Send a message

Queue a WhatsApp text or approved template message for a recipient.

Example request
POST /api/public/v1/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "to": "+15551230000",
  "type": "template",
  "kind": "transactional",
  "template": {
    "template_id": "appointment_confirmation",
    "variables": { "name": "Sample Patient", "time": "10:30 AM" }
  },
  "idempotency_key": "9ac86af7-43f5-4b5d-a1e2-2b57a0743324"
}
Example response
{
  "message_id": "msg_example",
  "conversation_id": "conv_example",
  "status": "queued"
}

Error handling

400validation error

Check the recipient, type, content, and idempotency key.

403INSUFFICIENT_SCOPE

Create a key with messages:send.

403CONSENT_BLOCKED

Do not retry until the recipient has valid consent for this message.

409WINDOW_CLOSED

Use an approved template when the customer-service window is closed.

429RATE_LIMITED

Wait for the next minute and retry with the same idempotency key.

Best practices

  • Create a unique idempotency key for each intended message.
  • Keep the same key when retrying the same request.
  • Use approved templates outside the reply window.
  • Treat queued as accepted for delivery, not delivered.
Try this endpoint in the console
Production checklist

Best practices

  • ✓Keep patient content out of request logs.
  • ✓Do not retry consent or suppression denials.
  • ✓Use approved templates for messages outside the reply window.
  • ✓Keep idempotent retries byte-for-byte equivalent.
Interactive console

Try a supported API

Requests go directly from this browser tab to the API environment you choose. Keys and responses are held in memory only and are cleared when the page closes.

Do not use real patient data in tests
POST/api/public/v1/messages
Response
Ready when you are

Enter a test key, review the sample request, and send it. The response will appear here.

Equivalent cURL example
curl -X POST 'https://api.connect.globalclinic.app/api/public/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{
  "to": "+15551230000",
  "type": "template",
  "kind": "transactional",
  "template": {
    "template_id": "appointment_confirmation",
    "variables": { "name": "Sample Patient", "time": "10:30 AM" }
  },
  "idempotency_key": "9ac86af7-43f5-4b5d-a1e2-2b57a0743324"
}'
Required scopemessages:send

Queue a WhatsApp text or approved template message for a recipient.

Next steps