Communication API

Create communication id SMS

post

Step 1 of sending a message: generates a communicationId for the given channel and patient contact. No message is sent and no resource is created by this call alone — pass the returned communicationId to POST /{communicationId}/messages to actually send it. Confirmed against welikan-communication-proxy-service (CommunicationController.createCommunicationId).

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

Body

channelstring · enumRequiredPossible values:

patientContactIdstring · uuidRequired

instancePhoneIdstring · uuidOptional

Required for SMS/VOICE_CALL if patientContactPhoneNumber is not the default.

patientContactPhoneNumberstringOptional

E.164 format. If omitted for SMS/VOICE_CALL, the patient contact's default phone is used.

Responses

200

Communication ID generated (no resource is persisted).

application/json

communicationIdstringOptional

Opaque token to pass to the send-message endpoint. Not a persisted resource — it is a Base64 encoding of the request above, decoded server-side on the next call.

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

post/{tenantName}/{instanceName}/communications

POST /{tenantName}/{instanceName}/communications HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 167

{
  "channel": "SMS",
  "patientContactId": "123e4567-e89b-12d3-a456-426614174000",
  "instancePhoneId": "123e4567-e89b-12d3-a456-426614174000",
  "patientContactPhoneNumber": "text"
}

{
  "communicationId": "text"
}

Send message

post

Step 2 of sending a message: sends the actual message on the channel established by the communicationId. Request shape depends on that channel: SMS needs message; Email needs message + subject (+ optional secure); Voice Call takes only recorded. For SMS/Email, use multipart/form-data instead to attach files via attachmentsAsFiles. The response is the created SMS/Email/Voice Call record from the underlying resource, matching the corresponding resource schema in the SMS/Email/Calls sections of this API. Confirmed against welikan-communication-proxy-service (MessageController.createAndSendMessage), which proxies to the corresponding welikan monolith endpoint.

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

communicationIdstringRequired

Opaque token returned by POST /communications.

Body

or

or

Responses

200

Message sent — response shape matches the SMS/Email/Voice Call resource for the channel used.

application/json

or

or

400

Validation error, invalid communicationId, or invalid channel.

application/json

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Downstream communication error or unexpected failure.

application/json

post/{tenantName}/{instanceName}/{communicationId}/messages

POST /{tenantName}/{instanceName}/{communicationId}/messages HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 164

{
  "message": "text",
  "attachmentsFromTemplate": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "originalName": "text",
      "size": 1,
      "contentType": "text",
      "storageKey": "text"
    }
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "123e4567-e89b-12d3-a456-426614174000",
  "updatedBy": "123e4567-e89b-12d3-a456-426614174000",
  "createdByName": "text",
  "updatedByName": "text",
  "sendNow": true,
  "sentAt": "2026-01-01T00:00:00.000Z",
  "receivedAt": "2026-01-01T00:00:00.000Z",
  "deletedAt": "2026-01-01T00:00:00.000Z",
  "date": "2026-01-01T00:00:00.000Z",
  "careTeam": "text",
  "patientInfo": "text",
  "sender": "123e4567-e89b-12d3-a456-426614174000",
  "senderType": "CS_TOOL_CLIENT",
  "senderName": "text",
  "from": "text",
  "receiver": "123e4567-e89b-12d3-a456-426614174000",
  "receiverType": "CS_TOOL_CLIENT",
  "receiverName": "text",
  "to": "text",
  "direction": "OUT",
  "externalId": "text",
  "starred": true,
  "errorMessage": "text",
  "assignedBy": "123e4567-e89b-12d3-a456-426614174000",
  "assignedByName": "text",
  "hasHistory": true,
  "unrecognized": true,
  "message": "text",
  "parts": 1,
  "status": "SCHEDULED",
  "messageType": "CARE_TEAM",
  "phoneId": "123e4567-e89b-12d3-a456-426614174000",
  "attachments": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "originalName": "text",
      "size": 1,
      "contentType": "text",
      "storageKey": "text"
    }
  ],
  "attachmentsFromTemplate": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "originalName": "text",
      "size": 1,
      "contentType": "text",
      "storageKey": "text"
    }
  ],
  "skipEvent": true
}