> For the complete documentation index, see [llms.txt](https://docs.welkinhealth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.welkinhealth.com/api-reference/communication-api.md).

# Communication API

## Create communication

> Creates a communication with a patient contact on the \`phone\`, \`email\` or \`chat\` channel. The request body depends on \`channel\`. To send messages on it, use \*\*Send a message on a communication\*\*.

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Communication API","description":""}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CommCenterCreatePhoneCommunicationRequest":{"allOf":[{"$ref":"#/components/schemas/CommCenterCreateCommunicationRequest"},{"type":"object","properties":{"patientContactPhoneNumber":{"type":"string"},"instancePhoneNumber":{"type":"string"},"instancePhoneId":{"type":"string"}},"required":["patientContactPhoneNumber","instancePhoneNumber","instancePhoneId"]}]},"CommCenterCreateCommunicationRequest":{"type":"object","properties":{"patientContactId":{"type":"string"},"channel":{"type":"string"},"status":{"description":"Status of the created communication. Defaults to `closed`; send `open` to keep the conversation open after the first message.","type":"string"}},"required":["patientContactId","channel"]},"CommCenterCreateEmailCommunicationRequest":{"allOf":[{"$ref":"#/components/schemas/CommCenterCreateCommunicationRequest"},{"type":"object","properties":{"patientContactEmail":{"type":"string","format":"email"},"userEmail":{"type":"string","format":"email"}},"required":["patientContactEmail","userEmail"]}]},"CommCenterCreateChatCommunicationRequest":{"allOf":[{"$ref":"#/components/schemas/CommCenterCreateCommunicationRequest"}]},"CommCenterCommunicationDetailsResponse":{"type":"object","discriminator":{"propertyName":"channel","mapping":{"phone":"#/components/schemas/CommCenterSmsCommunicationResponse","email":"#/components/schemas/CommCenterEmailCommunicationResponse","chat":"#/components/schemas/CommCenterChatCommunicationResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsCommunicationResponse"},{"$ref":"#/components/schemas/CommCenterEmailCommunicationResponse"},{"$ref":"#/components/schemas/CommCenterChatCommunicationResponse"}],"properties":{"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"}}},"CommCenterSmsCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"},{"type":"object","properties":{"patientContactPhoneNumber":{"type":"string"},"instancePhoneNumber":{"type":"string"},"instancePhoneId":{"type":"string","format":"uuid"}}}]},"CommCenterCommunicationResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"status":{"$ref":"#/components/schemas/CommCenterCommunicationStatus"},"category":{"$ref":"#/components/schemas/CommCenterCommunicationCategory"},"lastMessage":{"$ref":"#/components/schemas/CommCenterLastMessageResponse"},"patientContact":{"$ref":"#/components/schemas/CommCenterPatientContactResponse"},"assignee":{"$ref":"#/components/schemas/CommCenterUserResponse"},"events":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterCommunicationEventResponse"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastPatientContactMessageDate":{"type":"string","format":"date-time"}},"required":["id","channel","status","category","lastMessage","createdAt","updatedAt"]},"CommCenterCommunicationChannel":{"type":"string","enum":["phone","email","chat"]},"CommCenterCommunicationStatus":{"type":"string","enum":["open","closed"]},"CommCenterCommunicationCategory":{"type":"string","enum":["unrecognised","recognised"]},"CommCenterLastMessageResponse":{"discriminator":{"propertyName":"subchannel","mapping":{"sms":"#/components/schemas/CommCenterSmsMessageResponse","email":"#/components/schemas/CommCenterEmailMessageResponse","chat":"#/components/schemas/CommCenterChatMessageResponse","voice_call":"#/components/schemas/CommCenterVoiceCallMessageResponse","internal":"#/components/schemas/CommCenterInternalMessageResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsMessageResponse"},{"$ref":"#/components/schemas/CommCenterEmailMessageResponse"},{"$ref":"#/components/schemas/CommCenterChatMessageResponse"},{"$ref":"#/components/schemas/CommCenterVoiceCallMessageResponse"},{"$ref":"#/components/schemas/CommCenterInternalMessageResponse"}],"properties":{"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"}}},"CommCenterSmsMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"},"deliveryStatus":{"type":"string"},"errorMessage":{"type":"string"}},"required":["message","deliveryStatus"]}]},"CommCenterBaseMessageResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"},"direction":{"$ref":"#/components/schemas/CommCenterMessageDirection"},"senderType":{"$ref":"#/components/schemas/CommCenterMessageSenderType"},"user":{"$ref":"#/components/schemas/CommCenterUserResponse"},"createdAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"$ref":"#/components/schemas/CommCenterCreatedBy"},"updatedBy":{"$ref":"#/components/schemas/CommCenterUpdatedBy"},"externalReferenceId":{"type":"string"}},"required":["id","channel","subchannel","direction","senderType","createdAt","updatedAt"]},"CommCenterCommunicationSubchannel":{"type":"string","enum":["sms","voice_call","email","chat","internal"]},"CommCenterMessageDirection":{"type":"string","enum":["incoming","outgoing"]},"CommCenterMessageSenderType":{"type":"string","enum":["patient","contact","unrecognised","user","api_client","system"]},"CommCenterUserResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"enabled":{"type":"boolean"}},"required":["id","firstName","lastName"]},"CommCenterCreatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"}}},"CommCenterUpdatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"},"email":{"type":"string"}}},"CommCenterEmailMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"deliveryStatus":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"bodyType":{"$ref":"#/components/schemas/CommCenterEmailBodyType"},"secure":{"type":"boolean"},"starred":{"type":"boolean"},"emailFrom":{"type":"string"},"emailTo":{"type":"string"},"errorMessage":{"type":"string"}}}]},"CommCenterEmailBodyType":{"type":"string","enum":["plain_text","html"]},"CommCenterChatMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterVoiceCallMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"userPhone":{"type":"string"},"childCallStatus":{"type":"string"},"parentCallStatus":{"type":"string"},"recordingDuration":{"type":"integer"},"recording":{"$ref":"#/components/schemas/CommCenterRecordingFileResponse"}},"required":["parentCallStatus"]}]},"CommCenterRecordingFileResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"sizeInBytes":{"type":"integer","format":"int64"},"contentType":{"type":"string"},"url":{"type":"string"}}},"CommCenterInternalMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterPatientContactResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string"},"phoneNumber":{"type":"string"},"secondaryPhoneNumber":{"type":"string"},"relation":{"type":"string"},"email":{"type":"string"},"secondaryEmail":{"type":"string"},"deleted":{"type":"boolean"},"type":{"$ref":"#/components/schemas/CommCenterPatientContactType"},"pointOfContact":{"$ref":"#/components/schemas/CommCenterPointOfContactResponse"},"sourcePatient":{"$ref":"#/components/schemas/CommCenterPatientContactResponse"}},"required":["id","firstName","lastName"]},"CommCenterPatientContactType":{"type":"string","enum":["patient","contact"]},"CommCenterPointOfContactResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}},"CommCenterCommunicationEventResponse":{"anyOf":[{"$ref":"#/components/schemas/CommCenterPatientContactUpdatedCommunicationEventResponse"}]},"CommCenterPatientContactUpdatedCommunicationEventResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseCommunicationEvent"},{"type":"object","properties":{"oldValue":{"type":"string"},"newValue":{"type":"string"}}}]},"CommCenterBaseCommunicationEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CommCenterCommunicationEventType"},"timestamp":{"type":"string","format":"date-time"}}},"CommCenterCommunicationEventType":{"type":"string","enum":["patient_contact_phone_number_changed","patient_contact_email_changed"]},"CommCenterEmailCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"},{"type":"object","properties":{"patientContactEmail":{"type":"string"},"userEmail":{"type":"string"},"lastEmailSubject":{"type":"string"}}}]},"CommCenterChatCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"}]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/comm-center/communications":{"post":{"tags":["Communication API"],"summary":"Create communication","operationId":"CommCenter_Create_communication","description":"Creates a communication with a patient contact on the `phone`, `email` or `chat` channel. The request body depends on `channel`. To send messages on it, use **Send a message on a communication**.","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"}],"requestBody":{"content":{"application/json":{"schema":{"discriminator":{"propertyName":"channel","mapping":{"phone":"#/components/schemas/CommCenterCreatePhoneCommunicationRequest","email":"#/components/schemas/CommCenterCreateEmailCommunicationRequest","chat":"#/components/schemas/CommCenterCreateChatCommunicationRequest"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterCreatePhoneCommunicationRequest"},{"$ref":"#/components/schemas/CommCenterCreateEmailCommunicationRequest"},{"$ref":"#/components/schemas/CommCenterCreateChatCommunicationRequest"}]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommCenterCommunicationDetailsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Create communication with first message

> Create a communication and send its first message atomically. The created communication is \`closed\` unless the communication part explicitly asks for \`open\`.

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Communication API","description":""}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CommCenterCreateCommunicationRequest":{"type":"object","properties":{"patientContactId":{"type":"string"},"channel":{"type":"string"},"status":{"description":"Status of the created communication. Defaults to `closed`; send `open` to keep the conversation open after the first message.","type":"string"}},"required":["patientContactId","channel"]},"CommCenterCreateMessageRequest":{"type":"object","properties":{"subchannel":{"type":"string"},"senderId":{"type":"string","description":"Id of the user"},"externalReferenceId":{"type":"string","minLength":1,"maxLength":255,"description":"Caller's own id for the message, stored and returned as is. It does not have to be unique."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":255,"description":"Key generated by the caller for this send; reuse it only to retry the same send. A request with a key the caller has already used returns the original message (for `with-message`, its communication) without sending it again, whatever its body. Keys never expire."}},"discriminator":{"propertyName":"subchannel","mapping":{"sms":"#/components/schemas/CommCenterCreateSmsMessageRequest","email":"#/components/schemas/CommCenterCreateEmailMessageRequest","chat":"#/components/schemas/CommCenterCreateChatMessageRequest","internal":"#/components/schemas/CommCenterCreateInternalMessageRequest"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterCreateSmsMessageRequest"},{"$ref":"#/components/schemas/CommCenterCreateEmailMessageRequest"},{"$ref":"#/components/schemas/CommCenterCreateChatMessageRequest"},{"$ref":"#/components/schemas/CommCenterCreateInternalMessageRequest"}],"required":["subchannel","senderId"]},"CommCenterCreateSmsMessageRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":1600}},"required":["message"]},"CommCenterCreateEmailMessageRequest":{"type":"object","properties":{"senderEmail":{"type":"string","format":"email"},"subject":{"type":"string","maxLength":2000},"body":{"type":"string"},"bodyType":{"type":"string"},"secure":{"type":"boolean","default":false},"starred":{"type":"boolean","default":false},"inReplyTo":{"type":"string","format":"uuid","description":"Id of the message to reply"}},"required":["senderEmail","subject","body","bodyType"]},"CommCenterCreateChatMessageRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":5000}},"required":["message"]},"CommCenterCreateInternalMessageRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":5000},"mentionedUserIds":{"type":"array","items":{"type":"string","format":"uuid"},"uniqueItems":true}},"required":["message"]},"CommCenterCommunicationDetailsResponse":{"type":"object","discriminator":{"propertyName":"channel","mapping":{"phone":"#/components/schemas/CommCenterSmsCommunicationResponse","email":"#/components/schemas/CommCenterEmailCommunicationResponse","chat":"#/components/schemas/CommCenterChatCommunicationResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsCommunicationResponse"},{"$ref":"#/components/schemas/CommCenterEmailCommunicationResponse"},{"$ref":"#/components/schemas/CommCenterChatCommunicationResponse"}],"properties":{"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"}}},"CommCenterSmsCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"},{"type":"object","properties":{"patientContactPhoneNumber":{"type":"string"},"instancePhoneNumber":{"type":"string"},"instancePhoneId":{"type":"string","format":"uuid"}}}]},"CommCenterCommunicationResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"status":{"$ref":"#/components/schemas/CommCenterCommunicationStatus"},"category":{"$ref":"#/components/schemas/CommCenterCommunicationCategory"},"lastMessage":{"$ref":"#/components/schemas/CommCenterLastMessageResponse"},"patientContact":{"$ref":"#/components/schemas/CommCenterPatientContactResponse"},"assignee":{"$ref":"#/components/schemas/CommCenterUserResponse"},"events":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterCommunicationEventResponse"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastPatientContactMessageDate":{"type":"string","format":"date-time"}},"required":["id","channel","status","category","lastMessage","createdAt","updatedAt"]},"CommCenterCommunicationChannel":{"type":"string","enum":["phone","email","chat"]},"CommCenterCommunicationStatus":{"type":"string","enum":["open","closed"]},"CommCenterCommunicationCategory":{"type":"string","enum":["unrecognised","recognised"]},"CommCenterLastMessageResponse":{"discriminator":{"propertyName":"subchannel","mapping":{"sms":"#/components/schemas/CommCenterSmsMessageResponse","email":"#/components/schemas/CommCenterEmailMessageResponse","chat":"#/components/schemas/CommCenterChatMessageResponse","voice_call":"#/components/schemas/CommCenterVoiceCallMessageResponse","internal":"#/components/schemas/CommCenterInternalMessageResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsMessageResponse"},{"$ref":"#/components/schemas/CommCenterEmailMessageResponse"},{"$ref":"#/components/schemas/CommCenterChatMessageResponse"},{"$ref":"#/components/schemas/CommCenterVoiceCallMessageResponse"},{"$ref":"#/components/schemas/CommCenterInternalMessageResponse"}],"properties":{"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"}}},"CommCenterSmsMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"},"deliveryStatus":{"type":"string"},"errorMessage":{"type":"string"}},"required":["message","deliveryStatus"]}]},"CommCenterBaseMessageResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"},"direction":{"$ref":"#/components/schemas/CommCenterMessageDirection"},"senderType":{"$ref":"#/components/schemas/CommCenterMessageSenderType"},"user":{"$ref":"#/components/schemas/CommCenterUserResponse"},"createdAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"$ref":"#/components/schemas/CommCenterCreatedBy"},"updatedBy":{"$ref":"#/components/schemas/CommCenterUpdatedBy"},"externalReferenceId":{"type":"string"}},"required":["id","channel","subchannel","direction","senderType","createdAt","updatedAt"]},"CommCenterCommunicationSubchannel":{"type":"string","enum":["sms","voice_call","email","chat","internal"]},"CommCenterMessageDirection":{"type":"string","enum":["incoming","outgoing"]},"CommCenterMessageSenderType":{"type":"string","enum":["patient","contact","unrecognised","user","api_client","system"]},"CommCenterUserResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"enabled":{"type":"boolean"}},"required":["id","firstName","lastName"]},"CommCenterCreatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"}}},"CommCenterUpdatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"},"email":{"type":"string"}}},"CommCenterEmailMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"deliveryStatus":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"bodyType":{"$ref":"#/components/schemas/CommCenterEmailBodyType"},"secure":{"type":"boolean"},"starred":{"type":"boolean"},"emailFrom":{"type":"string"},"emailTo":{"type":"string"},"errorMessage":{"type":"string"}}}]},"CommCenterEmailBodyType":{"type":"string","enum":["plain_text","html"]},"CommCenterChatMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterVoiceCallMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"userPhone":{"type":"string"},"childCallStatus":{"type":"string"},"parentCallStatus":{"type":"string"},"recordingDuration":{"type":"integer"},"recording":{"$ref":"#/components/schemas/CommCenterRecordingFileResponse"}},"required":["parentCallStatus"]}]},"CommCenterRecordingFileResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"sizeInBytes":{"type":"integer","format":"int64"},"contentType":{"type":"string"},"url":{"type":"string"}}},"CommCenterInternalMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterPatientContactResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string"},"phoneNumber":{"type":"string"},"secondaryPhoneNumber":{"type":"string"},"relation":{"type":"string"},"email":{"type":"string"},"secondaryEmail":{"type":"string"},"deleted":{"type":"boolean"},"type":{"$ref":"#/components/schemas/CommCenterPatientContactType"},"pointOfContact":{"$ref":"#/components/schemas/CommCenterPointOfContactResponse"},"sourcePatient":{"$ref":"#/components/schemas/CommCenterPatientContactResponse"}},"required":["id","firstName","lastName"]},"CommCenterPatientContactType":{"type":"string","enum":["patient","contact"]},"CommCenterPointOfContactResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}},"CommCenterCommunicationEventResponse":{"anyOf":[{"$ref":"#/components/schemas/CommCenterPatientContactUpdatedCommunicationEventResponse"}]},"CommCenterPatientContactUpdatedCommunicationEventResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseCommunicationEvent"},{"type":"object","properties":{"oldValue":{"type":"string"},"newValue":{"type":"string"}}}]},"CommCenterBaseCommunicationEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CommCenterCommunicationEventType"},"timestamp":{"type":"string","format":"date-time"}}},"CommCenterCommunicationEventType":{"type":"string","enum":["patient_contact_phone_number_changed","patient_contact_email_changed"]},"CommCenterEmailCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"},{"type":"object","properties":{"patientContactEmail":{"type":"string"},"userEmail":{"type":"string"},"lastEmailSubject":{"type":"string"}}}]},"CommCenterChatCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"}]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/comm-center/communications/with-message":{"post":{"tags":["Communication API"],"summary":"Create communication with first message","operationId":"CommCenter_Create_communication_with_message","description":"Create a communication and send its first message atomically. The created communication is `closed` unless the communication part explicitly asks for `open`.","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"communication":{"$ref":"#/components/schemas/CommCenterCreateCommunicationRequest"},"message":{"$ref":"#/components/schemas/CommCenterCreateMessageRequest"},"attachments":{"type":"array","description":"Optional attachments for the first message; validated per message subchannel.","items":{"type":"string","format":"binary"}}},"required":["communication","message"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommCenterCommunicationDetailsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Get communication by ID

> Returns a communication with its details.

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Communication API","description":""}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CommCenterCommunicationDetailsResponse":{"type":"object","discriminator":{"propertyName":"channel","mapping":{"phone":"#/components/schemas/CommCenterSmsCommunicationResponse","email":"#/components/schemas/CommCenterEmailCommunicationResponse","chat":"#/components/schemas/CommCenterChatCommunicationResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsCommunicationResponse"},{"$ref":"#/components/schemas/CommCenterEmailCommunicationResponse"},{"$ref":"#/components/schemas/CommCenterChatCommunicationResponse"}],"properties":{"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"}}},"CommCenterSmsCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"},{"type":"object","properties":{"patientContactPhoneNumber":{"type":"string"},"instancePhoneNumber":{"type":"string"},"instancePhoneId":{"type":"string","format":"uuid"}}}]},"CommCenterCommunicationResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"status":{"$ref":"#/components/schemas/CommCenterCommunicationStatus"},"category":{"$ref":"#/components/schemas/CommCenterCommunicationCategory"},"lastMessage":{"$ref":"#/components/schemas/CommCenterLastMessageResponse"},"patientContact":{"$ref":"#/components/schemas/CommCenterPatientContactResponse"},"assignee":{"$ref":"#/components/schemas/CommCenterUserResponse"},"events":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterCommunicationEventResponse"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastPatientContactMessageDate":{"type":"string","format":"date-time"}},"required":["id","channel","status","category","lastMessage","createdAt","updatedAt"]},"CommCenterCommunicationChannel":{"type":"string","enum":["phone","email","chat"]},"CommCenterCommunicationStatus":{"type":"string","enum":["open","closed"]},"CommCenterCommunicationCategory":{"type":"string","enum":["unrecognised","recognised"]},"CommCenterLastMessageResponse":{"discriminator":{"propertyName":"subchannel","mapping":{"sms":"#/components/schemas/CommCenterSmsMessageResponse","email":"#/components/schemas/CommCenterEmailMessageResponse","chat":"#/components/schemas/CommCenterChatMessageResponse","voice_call":"#/components/schemas/CommCenterVoiceCallMessageResponse","internal":"#/components/schemas/CommCenterInternalMessageResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsMessageResponse"},{"$ref":"#/components/schemas/CommCenterEmailMessageResponse"},{"$ref":"#/components/schemas/CommCenterChatMessageResponse"},{"$ref":"#/components/schemas/CommCenterVoiceCallMessageResponse"},{"$ref":"#/components/schemas/CommCenterInternalMessageResponse"}],"properties":{"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"}}},"CommCenterSmsMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"},"deliveryStatus":{"type":"string"},"errorMessage":{"type":"string"}},"required":["message","deliveryStatus"]}]},"CommCenterBaseMessageResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"},"direction":{"$ref":"#/components/schemas/CommCenterMessageDirection"},"senderType":{"$ref":"#/components/schemas/CommCenterMessageSenderType"},"user":{"$ref":"#/components/schemas/CommCenterUserResponse"},"createdAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"$ref":"#/components/schemas/CommCenterCreatedBy"},"updatedBy":{"$ref":"#/components/schemas/CommCenterUpdatedBy"},"externalReferenceId":{"type":"string"}},"required":["id","channel","subchannel","direction","senderType","createdAt","updatedAt"]},"CommCenterCommunicationSubchannel":{"type":"string","enum":["sms","voice_call","email","chat","internal"]},"CommCenterMessageDirection":{"type":"string","enum":["incoming","outgoing"]},"CommCenterMessageSenderType":{"type":"string","enum":["patient","contact","unrecognised","user","api_client","system"]},"CommCenterUserResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"enabled":{"type":"boolean"}},"required":["id","firstName","lastName"]},"CommCenterCreatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"}}},"CommCenterUpdatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"},"email":{"type":"string"}}},"CommCenterEmailMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"deliveryStatus":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"bodyType":{"$ref":"#/components/schemas/CommCenterEmailBodyType"},"secure":{"type":"boolean"},"starred":{"type":"boolean"},"emailFrom":{"type":"string"},"emailTo":{"type":"string"},"errorMessage":{"type":"string"}}}]},"CommCenterEmailBodyType":{"type":"string","enum":["plain_text","html"]},"CommCenterChatMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterVoiceCallMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"userPhone":{"type":"string"},"childCallStatus":{"type":"string"},"parentCallStatus":{"type":"string"},"recordingDuration":{"type":"integer"},"recording":{"$ref":"#/components/schemas/CommCenterRecordingFileResponse"}},"required":["parentCallStatus"]}]},"CommCenterRecordingFileResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"sizeInBytes":{"type":"integer","format":"int64"},"contentType":{"type":"string"},"url":{"type":"string"}}},"CommCenterInternalMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterPatientContactResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string"},"phoneNumber":{"type":"string"},"secondaryPhoneNumber":{"type":"string"},"relation":{"type":"string"},"email":{"type":"string"},"secondaryEmail":{"type":"string"},"deleted":{"type":"boolean"},"type":{"$ref":"#/components/schemas/CommCenterPatientContactType"},"pointOfContact":{"$ref":"#/components/schemas/CommCenterPointOfContactResponse"},"sourcePatient":{"$ref":"#/components/schemas/CommCenterPatientContactResponse"}},"required":["id","firstName","lastName"]},"CommCenterPatientContactType":{"type":"string","enum":["patient","contact"]},"CommCenterPointOfContactResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}},"CommCenterCommunicationEventResponse":{"anyOf":[{"$ref":"#/components/schemas/CommCenterPatientContactUpdatedCommunicationEventResponse"}]},"CommCenterPatientContactUpdatedCommunicationEventResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseCommunicationEvent"},{"type":"object","properties":{"oldValue":{"type":"string"},"newValue":{"type":"string"}}}]},"CommCenterBaseCommunicationEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CommCenterCommunicationEventType"},"timestamp":{"type":"string","format":"date-time"}}},"CommCenterCommunicationEventType":{"type":"string","enum":["patient_contact_phone_number_changed","patient_contact_email_changed"]},"CommCenterEmailCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"},{"type":"object","properties":{"patientContactEmail":{"type":"string"},"userEmail":{"type":"string"},"lastEmailSubject":{"type":"string"}}}]},"CommCenterChatCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"}]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/comm-center/communications/{communicationId}":{"get":{"tags":["Communication API"],"summary":"Get communication by ID","operationId":"CommCenter_Get_communication","description":"Returns a communication with its details.","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"communicationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommCenterCommunicationDetailsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Send a message on a communication

> Sends a message on an existing communication. The \`subchannel\` must belong to the communication's channel, otherwise the request fails with \`400\` (for example \`Message subchannel 'SMS' does not match communication channel 'EMAIL'.\`). \`senderId\` is the Welkin user the message is sent as; that user must be on the patient contact's care team or have region/territory access to it. Chat messages sent by an API client are attributed to this user. SMS messages are limited to 1600 characters.

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Communication API","description":""}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CommCenterCreateMessageRequest":{"type":"object","properties":{"subchannel":{"type":"string"},"senderId":{"type":"string","description":"Id of the user"},"externalReferenceId":{"type":"string","minLength":1,"maxLength":255,"description":"Caller's own id for the message, stored and returned as is. It does not have to be unique."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":255,"description":"Key generated by the caller for this send; reuse it only to retry the same send. A request with a key the caller has already used returns the original message (for `with-message`, its communication) without sending it again, whatever its body. Keys never expire."}},"discriminator":{"propertyName":"subchannel","mapping":{"sms":"#/components/schemas/CommCenterCreateSmsMessageRequest","email":"#/components/schemas/CommCenterCreateEmailMessageRequest","chat":"#/components/schemas/CommCenterCreateChatMessageRequest","internal":"#/components/schemas/CommCenterCreateInternalMessageRequest"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterCreateSmsMessageRequest"},{"$ref":"#/components/schemas/CommCenterCreateEmailMessageRequest"},{"$ref":"#/components/schemas/CommCenterCreateChatMessageRequest"},{"$ref":"#/components/schemas/CommCenterCreateInternalMessageRequest"}],"required":["subchannel","senderId"]},"CommCenterCreateSmsMessageRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":1600}},"required":["message"]},"CommCenterCreateEmailMessageRequest":{"type":"object","properties":{"senderEmail":{"type":"string","format":"email"},"subject":{"type":"string","maxLength":2000},"body":{"type":"string"},"bodyType":{"type":"string"},"secure":{"type":"boolean","default":false},"starred":{"type":"boolean","default":false},"inReplyTo":{"type":"string","format":"uuid","description":"Id of the message to reply"}},"required":["senderEmail","subject","body","bodyType"]},"CommCenterCreateChatMessageRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":5000}},"required":["message"]},"CommCenterCreateInternalMessageRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":5000},"mentionedUserIds":{"type":"array","items":{"type":"string","format":"uuid"},"uniqueItems":true}},"required":["message"]},"CommCenterMessageDetailsResponse":{"discriminator":{"propertyName":"subchannel","mapping":{"sms":"#/components/schemas/CommCenterSmsMessageDetailsResponse","email":"#/components/schemas/CommCenterEmailMessageDetailsResponse","chat":"#/components/schemas/CommCenterChatMessageDetailsResponse","voice_call":"#/components/schemas/CommCenterVoiceCallMessageDetailsResponse","internal":"#/components/schemas/CommCenterInternalMessageDetailsResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsMessageDetailsResponse"},{"$ref":"#/components/schemas/CommCenterEmailMessageDetailsResponse"},{"$ref":"#/components/schemas/CommCenterChatMessageDetailsResponse"},{"$ref":"#/components/schemas/CommCenterVoiceCallMessageDetailsResponse"},{"$ref":"#/components/schemas/CommCenterInternalMessageDetailsResponse"}],"properties":{"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"}}},"CommCenterSmsMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterSmsMessageResponse"},{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterAttachmentResponse"}}}}]},"CommCenterSmsMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"},"deliveryStatus":{"type":"string"},"errorMessage":{"type":"string"}},"required":["message","deliveryStatus"]}]},"CommCenterBaseMessageResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"},"direction":{"$ref":"#/components/schemas/CommCenterMessageDirection"},"senderType":{"$ref":"#/components/schemas/CommCenterMessageSenderType"},"user":{"$ref":"#/components/schemas/CommCenterUserResponse"},"createdAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"$ref":"#/components/schemas/CommCenterCreatedBy"},"updatedBy":{"$ref":"#/components/schemas/CommCenterUpdatedBy"},"externalReferenceId":{"type":"string"}},"required":["id","channel","subchannel","direction","senderType","createdAt","updatedAt"]},"CommCenterCommunicationChannel":{"type":"string","enum":["phone","email","chat"]},"CommCenterCommunicationSubchannel":{"type":"string","enum":["sms","voice_call","email","chat","internal"]},"CommCenterMessageDirection":{"type":"string","enum":["incoming","outgoing"]},"CommCenterMessageSenderType":{"type":"string","enum":["patient","contact","unrecognised","user","api_client","system"]},"CommCenterUserResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"enabled":{"type":"boolean"}},"required":["id","firstName","lastName"]},"CommCenterCreatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"}}},"CommCenterUpdatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"},"email":{"type":"string"}}},"CommCenterAttachmentResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"sizeInBytes":{"type":"integer","format":"int64"},"contentType":{"type":"string"},"url":{"type":"string"}}},"CommCenterEmailMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterEmailMessageResponse"},{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterAttachmentResponse"}}}}]},"CommCenterEmailMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"deliveryStatus":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"bodyType":{"$ref":"#/components/schemas/CommCenterEmailBodyType"},"secure":{"type":"boolean"},"starred":{"type":"boolean"},"emailFrom":{"type":"string"},"emailTo":{"type":"string"},"errorMessage":{"type":"string"}}}]},"CommCenterEmailBodyType":{"type":"string","enum":["plain_text","html"]},"CommCenterChatMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterChatMessageResponse"},{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterAttachmentResponse"}}}}]},"CommCenterChatMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterVoiceCallMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterVoiceCallMessageResponse"}]},"CommCenterVoiceCallMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"userPhone":{"type":"string"},"childCallStatus":{"type":"string"},"parentCallStatus":{"type":"string"},"recordingDuration":{"type":"integer"},"recording":{"$ref":"#/components/schemas/CommCenterRecordingFileResponse"}},"required":["parentCallStatus"]}]},"CommCenterRecordingFileResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"sizeInBytes":{"type":"integer","format":"int64"},"contentType":{"type":"string"},"url":{"type":"string"}}},"CommCenterInternalMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterInternalMessageResponse"},{"type":"object","properties":{"mentionedUsers":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterUserResponse"}}}}]},"CommCenterInternalMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/comm-center/communications/{communicationId}/messages":{"post":{"tags":["Communication API"],"summary":"Send a message on a communication","operationId":"CommCenter_Send_message_on_communication","description":"Sends a message on an existing communication. The `subchannel` must belong to the communication's channel, otherwise the request fails with `400` (for example `Message subchannel 'SMS' does not match communication channel 'EMAIL'.`). `senderId` is the Welkin user the message is sent as; that user must be on the patient contact's care team or have region/territory access to it. Chat messages sent by an API client are attributed to this user. SMS messages are limited to 1600 characters.","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"communicationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/CommCenterCreateMessageRequest"},"attachments":{"type":"array","description":"MMS restrictions - jpeg and png types, 600 KB per file, 5 MB total size","items":{"type":"string","format":"binary"}}},"required":["message"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommCenterMessageDetailsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Assign communication to a user

> Assigns a user to a recognised communication.

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Communication API","description":""}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CommCenterCommunicationAssigneeRequest":{"type":"object","properties":{"userId":{"type":"string"}},"required":["userId"]},"CommCenterCommunicationDetailsResponse":{"type":"object","discriminator":{"propertyName":"channel","mapping":{"phone":"#/components/schemas/CommCenterSmsCommunicationResponse","email":"#/components/schemas/CommCenterEmailCommunicationResponse","chat":"#/components/schemas/CommCenterChatCommunicationResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsCommunicationResponse"},{"$ref":"#/components/schemas/CommCenterEmailCommunicationResponse"},{"$ref":"#/components/schemas/CommCenterChatCommunicationResponse"}],"properties":{"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"}}},"CommCenterSmsCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"},{"type":"object","properties":{"patientContactPhoneNumber":{"type":"string"},"instancePhoneNumber":{"type":"string"},"instancePhoneId":{"type":"string","format":"uuid"}}}]},"CommCenterCommunicationResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"status":{"$ref":"#/components/schemas/CommCenterCommunicationStatus"},"category":{"$ref":"#/components/schemas/CommCenterCommunicationCategory"},"lastMessage":{"$ref":"#/components/schemas/CommCenterLastMessageResponse"},"patientContact":{"$ref":"#/components/schemas/CommCenterPatientContactResponse"},"assignee":{"$ref":"#/components/schemas/CommCenterUserResponse"},"events":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterCommunicationEventResponse"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastPatientContactMessageDate":{"type":"string","format":"date-time"}},"required":["id","channel","status","category","lastMessage","createdAt","updatedAt"]},"CommCenterCommunicationChannel":{"type":"string","enum":["phone","email","chat"]},"CommCenterCommunicationStatus":{"type":"string","enum":["open","closed"]},"CommCenterCommunicationCategory":{"type":"string","enum":["unrecognised","recognised"]},"CommCenterLastMessageResponse":{"discriminator":{"propertyName":"subchannel","mapping":{"sms":"#/components/schemas/CommCenterSmsMessageResponse","email":"#/components/schemas/CommCenterEmailMessageResponse","chat":"#/components/schemas/CommCenterChatMessageResponse","voice_call":"#/components/schemas/CommCenterVoiceCallMessageResponse","internal":"#/components/schemas/CommCenterInternalMessageResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsMessageResponse"},{"$ref":"#/components/schemas/CommCenterEmailMessageResponse"},{"$ref":"#/components/schemas/CommCenterChatMessageResponse"},{"$ref":"#/components/schemas/CommCenterVoiceCallMessageResponse"},{"$ref":"#/components/schemas/CommCenterInternalMessageResponse"}],"properties":{"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"}}},"CommCenterSmsMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"},"deliveryStatus":{"type":"string"},"errorMessage":{"type":"string"}},"required":["message","deliveryStatus"]}]},"CommCenterBaseMessageResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"},"direction":{"$ref":"#/components/schemas/CommCenterMessageDirection"},"senderType":{"$ref":"#/components/schemas/CommCenterMessageSenderType"},"user":{"$ref":"#/components/schemas/CommCenterUserResponse"},"createdAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"$ref":"#/components/schemas/CommCenterCreatedBy"},"updatedBy":{"$ref":"#/components/schemas/CommCenterUpdatedBy"},"externalReferenceId":{"type":"string"}},"required":["id","channel","subchannel","direction","senderType","createdAt","updatedAt"]},"CommCenterCommunicationSubchannel":{"type":"string","enum":["sms","voice_call","email","chat","internal"]},"CommCenterMessageDirection":{"type":"string","enum":["incoming","outgoing"]},"CommCenterMessageSenderType":{"type":"string","enum":["patient","contact","unrecognised","user","api_client","system"]},"CommCenterUserResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"enabled":{"type":"boolean"}},"required":["id","firstName","lastName"]},"CommCenterCreatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"}}},"CommCenterUpdatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"},"email":{"type":"string"}}},"CommCenterEmailMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"deliveryStatus":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"bodyType":{"$ref":"#/components/schemas/CommCenterEmailBodyType"},"secure":{"type":"boolean"},"starred":{"type":"boolean"},"emailFrom":{"type":"string"},"emailTo":{"type":"string"},"errorMessage":{"type":"string"}}}]},"CommCenterEmailBodyType":{"type":"string","enum":["plain_text","html"]},"CommCenterChatMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterVoiceCallMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"userPhone":{"type":"string"},"childCallStatus":{"type":"string"},"parentCallStatus":{"type":"string"},"recordingDuration":{"type":"integer"},"recording":{"$ref":"#/components/schemas/CommCenterRecordingFileResponse"}},"required":["parentCallStatus"]}]},"CommCenterRecordingFileResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"sizeInBytes":{"type":"integer","format":"int64"},"contentType":{"type":"string"},"url":{"type":"string"}}},"CommCenterInternalMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterPatientContactResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string"},"phoneNumber":{"type":"string"},"secondaryPhoneNumber":{"type":"string"},"relation":{"type":"string"},"email":{"type":"string"},"secondaryEmail":{"type":"string"},"deleted":{"type":"boolean"},"type":{"$ref":"#/components/schemas/CommCenterPatientContactType"},"pointOfContact":{"$ref":"#/components/schemas/CommCenterPointOfContactResponse"},"sourcePatient":{"$ref":"#/components/schemas/CommCenterPatientContactResponse"}},"required":["id","firstName","lastName"]},"CommCenterPatientContactType":{"type":"string","enum":["patient","contact"]},"CommCenterPointOfContactResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}},"CommCenterCommunicationEventResponse":{"anyOf":[{"$ref":"#/components/schemas/CommCenterPatientContactUpdatedCommunicationEventResponse"}]},"CommCenterPatientContactUpdatedCommunicationEventResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseCommunicationEvent"},{"type":"object","properties":{"oldValue":{"type":"string"},"newValue":{"type":"string"}}}]},"CommCenterBaseCommunicationEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CommCenterCommunicationEventType"},"timestamp":{"type":"string","format":"date-time"}}},"CommCenterCommunicationEventType":{"type":"string","enum":["patient_contact_phone_number_changed","patient_contact_email_changed"]},"CommCenterEmailCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"},{"type":"object","properties":{"patientContactEmail":{"type":"string"},"userEmail":{"type":"string"},"lastEmailSubject":{"type":"string"}}}]},"CommCenterChatCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"}]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/comm-center/communications/{communicationId}/assignee":{"post":{"tags":["Communication API"],"summary":"Assign communication to a user","operationId":"CommCenter_Assign_communication","description":"Assigns a user to a recognised communication.","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"communicationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommCenterCommunicationAssigneeRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommCenterCommunicationDetailsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Send a message to a patient contact

> Send a message to a patient contact. The message is added to the existing communication of the patient contact for the phone numbers (sms) or to its chat communication (chat), and a new \`closed\` communication is created when there is none. Every email starts a new communication. To send attachments, use \`multipart/form-data\` with this body as the \`message\` part (\`application/json\`) and each file as an \`attachments\` part; attachments are validated per message subchannel.

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Communication API","description":""}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CommCenterCreateCommunicationMessageRequest":{"type":"object","properties":{"patientContactId":{"type":"string"},"channel":{"type":"string"},"subchannel":{"type":"string"},"senderId":{"type":"string","description":"Id of the user"},"externalReferenceId":{"type":"string","minLength":1,"maxLength":255,"description":"Caller's own id for the message, stored and returned as is. It does not have to be unique."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":255,"description":"Key generated by the caller for this send; reuse it only to retry the same send. A request with a key the caller has already used returns the original message without sending it again, whatever its body. Keys never expire."}},"discriminator":{"propertyName":"subchannel","mapping":{"sms":"#/components/schemas/CommCenterCreateSmsCommunicationMessageRequest","email":"#/components/schemas/CommCenterCreateEmailCommunicationMessageRequest","chat":"#/components/schemas/CommCenterCreateChatCommunicationMessageRequest"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterCreateSmsCommunicationMessageRequest"},{"$ref":"#/components/schemas/CommCenterCreateEmailCommunicationMessageRequest"},{"$ref":"#/components/schemas/CommCenterCreateChatCommunicationMessageRequest"}],"required":["patientContactId","channel","subchannel","senderId"]},"CommCenterCreateSmsCommunicationMessageRequest":{"type":"object","properties":{"patientContactPhoneNumber":{"type":"string"},"instancePhoneNumber":{"type":"string"},"instancePhoneId":{"type":"string"},"message":{"type":"string","minLength":1,"maxLength":1600}},"required":["patientContactPhoneNumber","instancePhoneNumber","instancePhoneId","message"]},"CommCenterCreateEmailCommunicationMessageRequest":{"type":"object","properties":{"patientContactEmail":{"type":"string","format":"email"},"senderEmail":{"type":"string","format":"email"},"subject":{"type":"string","maxLength":2000},"body":{"type":"string"},"bodyType":{"type":"string"},"secure":{"type":"boolean","default":false}},"required":["patientContactEmail","senderEmail","subject","body","bodyType"]},"CommCenterCreateChatCommunicationMessageRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":5000}},"required":["message"]},"CommCenterCommunicationMessageDetailsResponse":{"discriminator":{"propertyName":"subchannel","mapping":{"sms":"#/components/schemas/CommCenterSmsCommunicationMessageDetailsResponse","email":"#/components/schemas/CommCenterEmailCommunicationMessageDetailsResponse","chat":"#/components/schemas/CommCenterChatCommunicationMessageDetailsResponse","voice_call":"#/components/schemas/CommCenterVoiceCallCommunicationMessageDetailsResponse","internal":"#/components/schemas/CommCenterInternalCommunicationMessageDetailsResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsCommunicationMessageDetailsResponse"},{"$ref":"#/components/schemas/CommCenterEmailCommunicationMessageDetailsResponse"},{"$ref":"#/components/schemas/CommCenterChatCommunicationMessageDetailsResponse"},{"$ref":"#/components/schemas/CommCenterVoiceCallCommunicationMessageDetailsResponse"},{"$ref":"#/components/schemas/CommCenterInternalCommunicationMessageDetailsResponse"}],"properties":{"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"}}},"CommCenterSmsCommunicationMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterSmsMessageDetailsResponse"},{"type":"object","properties":{"communicationId":{"type":"string","format":"uuid"}},"required":["communicationId"]}]},"CommCenterSmsMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterSmsMessageResponse"},{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterAttachmentResponse"}}}}]},"CommCenterSmsMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"},"deliveryStatus":{"type":"string"},"errorMessage":{"type":"string"}},"required":["message","deliveryStatus"]}]},"CommCenterBaseMessageResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"},"direction":{"$ref":"#/components/schemas/CommCenterMessageDirection"},"senderType":{"$ref":"#/components/schemas/CommCenterMessageSenderType"},"user":{"$ref":"#/components/schemas/CommCenterUserResponse"},"createdAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"$ref":"#/components/schemas/CommCenterCreatedBy"},"updatedBy":{"$ref":"#/components/schemas/CommCenterUpdatedBy"},"externalReferenceId":{"type":"string"}},"required":["id","channel","subchannel","direction","senderType","createdAt","updatedAt"]},"CommCenterCommunicationChannel":{"type":"string","enum":["phone","email","chat"]},"CommCenterCommunicationSubchannel":{"type":"string","enum":["sms","voice_call","email","chat","internal"]},"CommCenterMessageDirection":{"type":"string","enum":["incoming","outgoing"]},"CommCenterMessageSenderType":{"type":"string","enum":["patient","contact","unrecognised","user","api_client","system"]},"CommCenterUserResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"enabled":{"type":"boolean"}},"required":["id","firstName","lastName"]},"CommCenterCreatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"}}},"CommCenterUpdatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"},"email":{"type":"string"}}},"CommCenterAttachmentResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"sizeInBytes":{"type":"integer","format":"int64"},"contentType":{"type":"string"},"url":{"type":"string"}}},"CommCenterEmailCommunicationMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterEmailMessageDetailsResponse"},{"type":"object","properties":{"communicationId":{"type":"string","format":"uuid"}},"required":["communicationId"]}]},"CommCenterEmailMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterEmailMessageResponse"},{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterAttachmentResponse"}}}}]},"CommCenterEmailMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"deliveryStatus":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"bodyType":{"$ref":"#/components/schemas/CommCenterEmailBodyType"},"secure":{"type":"boolean"},"starred":{"type":"boolean"},"emailFrom":{"type":"string"},"emailTo":{"type":"string"},"errorMessage":{"type":"string"}}}]},"CommCenterEmailBodyType":{"type":"string","enum":["plain_text","html"]},"CommCenterChatCommunicationMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterChatMessageDetailsResponse"},{"type":"object","properties":{"communicationId":{"type":"string","format":"uuid"}},"required":["communicationId"]}]},"CommCenterChatMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterChatMessageResponse"},{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterAttachmentResponse"}}}}]},"CommCenterChatMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterVoiceCallCommunicationMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterVoiceCallMessageDetailsResponse"},{"type":"object","properties":{"communicationId":{"type":"string","format":"uuid"}},"required":["communicationId"]}]},"CommCenterVoiceCallMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterVoiceCallMessageResponse"}]},"CommCenterVoiceCallMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"userPhone":{"type":"string"},"childCallStatus":{"type":"string"},"parentCallStatus":{"type":"string"},"recordingDuration":{"type":"integer"},"recording":{"$ref":"#/components/schemas/CommCenterRecordingFileResponse"}},"required":["parentCallStatus"]}]},"CommCenterRecordingFileResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"sizeInBytes":{"type":"integer","format":"int64"},"contentType":{"type":"string"},"url":{"type":"string"}}},"CommCenterInternalCommunicationMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterInternalMessageDetailsResponse"},{"type":"object","properties":{"communicationId":{"type":"string","format":"uuid"}},"required":["communicationId"]}]},"CommCenterInternalMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterInternalMessageResponse"},{"type":"object","properties":{"mentionedUsers":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterUserResponse"}}}}]},"CommCenterInternalMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/comm-center/messages":{"post":{"tags":["Communication API"],"summary":"Send a message to a patient contact","operationId":"CommCenter_Send_message","description":"Send a message to a patient contact. The message is added to the existing communication of the patient contact for the phone numbers (sms) or to its chat communication (chat), and a new `closed` communication is created when there is none. Every email starts a new communication. To send attachments, use `multipart/form-data` with this body as the `message` part (`application/json`) and each file as an `attachments` part; attachments are validated per message subchannel.","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommCenterCreateCommunicationMessageRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommCenterCommunicationMessageDetailsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Get message by ID

> Get a message of any subchannel in the same shape as the send response returns it, with its current delivery status. The message is readable when its communication is accessible to the caller. A deleted message is returned with \`deletedAt\` set and its content cleared.

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Communication API","description":""}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CommCenterCommunicationMessageDetailsResponse":{"discriminator":{"propertyName":"subchannel","mapping":{"sms":"#/components/schemas/CommCenterSmsCommunicationMessageDetailsResponse","email":"#/components/schemas/CommCenterEmailCommunicationMessageDetailsResponse","chat":"#/components/schemas/CommCenterChatCommunicationMessageDetailsResponse","voice_call":"#/components/schemas/CommCenterVoiceCallCommunicationMessageDetailsResponse","internal":"#/components/schemas/CommCenterInternalCommunicationMessageDetailsResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsCommunicationMessageDetailsResponse"},{"$ref":"#/components/schemas/CommCenterEmailCommunicationMessageDetailsResponse"},{"$ref":"#/components/schemas/CommCenterChatCommunicationMessageDetailsResponse"},{"$ref":"#/components/schemas/CommCenterVoiceCallCommunicationMessageDetailsResponse"},{"$ref":"#/components/schemas/CommCenterInternalCommunicationMessageDetailsResponse"}],"properties":{"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"}}},"CommCenterSmsCommunicationMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterSmsMessageDetailsResponse"},{"type":"object","properties":{"communicationId":{"type":"string","format":"uuid"}},"required":["communicationId"]}]},"CommCenterSmsMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterSmsMessageResponse"},{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterAttachmentResponse"}}}}]},"CommCenterSmsMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"},"deliveryStatus":{"type":"string"},"errorMessage":{"type":"string"}},"required":["message","deliveryStatus"]}]},"CommCenterBaseMessageResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"},"direction":{"$ref":"#/components/schemas/CommCenterMessageDirection"},"senderType":{"$ref":"#/components/schemas/CommCenterMessageSenderType"},"user":{"$ref":"#/components/schemas/CommCenterUserResponse"},"createdAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"$ref":"#/components/schemas/CommCenterCreatedBy"},"updatedBy":{"$ref":"#/components/schemas/CommCenterUpdatedBy"},"externalReferenceId":{"type":"string"}},"required":["id","channel","subchannel","direction","senderType","createdAt","updatedAt"]},"CommCenterCommunicationChannel":{"type":"string","enum":["phone","email","chat"]},"CommCenterCommunicationSubchannel":{"type":"string","enum":["sms","voice_call","email","chat","internal"]},"CommCenterMessageDirection":{"type":"string","enum":["incoming","outgoing"]},"CommCenterMessageSenderType":{"type":"string","enum":["patient","contact","unrecognised","user","api_client","system"]},"CommCenterUserResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"enabled":{"type":"boolean"}},"required":["id","firstName","lastName"]},"CommCenterCreatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"}}},"CommCenterUpdatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"},"email":{"type":"string"}}},"CommCenterAttachmentResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"sizeInBytes":{"type":"integer","format":"int64"},"contentType":{"type":"string"},"url":{"type":"string"}}},"CommCenterEmailCommunicationMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterEmailMessageDetailsResponse"},{"type":"object","properties":{"communicationId":{"type":"string","format":"uuid"}},"required":["communicationId"]}]},"CommCenterEmailMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterEmailMessageResponse"},{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterAttachmentResponse"}}}}]},"CommCenterEmailMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"deliveryStatus":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"bodyType":{"$ref":"#/components/schemas/CommCenterEmailBodyType"},"secure":{"type":"boolean"},"starred":{"type":"boolean"},"emailFrom":{"type":"string"},"emailTo":{"type":"string"},"errorMessage":{"type":"string"}}}]},"CommCenterEmailBodyType":{"type":"string","enum":["plain_text","html"]},"CommCenterChatCommunicationMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterChatMessageDetailsResponse"},{"type":"object","properties":{"communicationId":{"type":"string","format":"uuid"}},"required":["communicationId"]}]},"CommCenterChatMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterChatMessageResponse"},{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterAttachmentResponse"}}}}]},"CommCenterChatMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterVoiceCallCommunicationMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterVoiceCallMessageDetailsResponse"},{"type":"object","properties":{"communicationId":{"type":"string","format":"uuid"}},"required":["communicationId"]}]},"CommCenterVoiceCallMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterVoiceCallMessageResponse"}]},"CommCenterVoiceCallMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"userPhone":{"type":"string"},"childCallStatus":{"type":"string"},"parentCallStatus":{"type":"string"},"recordingDuration":{"type":"integer"},"recording":{"$ref":"#/components/schemas/CommCenterRecordingFileResponse"}},"required":["parentCallStatus"]}]},"CommCenterRecordingFileResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"sizeInBytes":{"type":"integer","format":"int64"},"contentType":{"type":"string"},"url":{"type":"string"}}},"CommCenterInternalCommunicationMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterInternalMessageDetailsResponse"},{"type":"object","properties":{"communicationId":{"type":"string","format":"uuid"}},"required":["communicationId"]}]},"CommCenterInternalMessageDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterInternalMessageResponse"},{"type":"object","properties":{"mentionedUsers":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterUserResponse"}}}}]},"CommCenterInternalMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/comm-center/messages/{messageId}":{"get":{"tags":["Communication API"],"summary":"Get message by ID","operationId":"CommCenter_Get_message","description":"Get a message of any subchannel in the same shape as the send response returns it, with its current delivery status. The message is readable when its communication is accessible to the caller. A deleted message is returned with `deletedAt` set and its content cleared.","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"messageId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommCenterCommunicationMessageDetailsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Query user inbox by category

> Returns a page of communications from the user's inbox for the given category.

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Communication API","description":""}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CommCenterInboxRequest":{"type":"object","properties":{"statuses":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"unassigned":{"type":"boolean"},"searchTerm":{"type":"string","description":"Search term for partial matching by phone number, email or patient name"},"regions":{"type":"array","description":"Optional filter. Limit results to patient contacts in these regions/territories. A region with no territories means the whole region the user can access. Regions/territories the user cannot access are dropped before searching.\n","items":{"$ref":"#/components/schemas/CommCenterRegionTerritoryFilter"}},"cursor":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterCommunicationCursorField"}},"sort":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterSortCriteria"}},"size":{"type":"integer","minimum":1,"maximum":200,"default":15}}},"CommCenterRegionTerritoryFilter":{"type":"object","required":["region"],"properties":{"region":{"type":"string"},"territories":{"type":"array","items":{"type":"string"}}}},"CommCenterCommunicationCursorField":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/CommCenterCommunicationSortField"},"value":{"type":"string"}}},"CommCenterCommunicationSortField":{"type":"string","enum":["id","lastPatientContactMessageDate","createdAt","userLastMessages.updatedAt"]},"CommCenterSortCriteria":{"type":"object","required":["field"],"properties":{"field":{"$ref":"#/components/schemas/CommCenterCommunicationSortField"},"direction":{"type":"string","enum":["asc","desc"]}}},"CommCenterCommunicationWindowResponse":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterCommunicationDetailsResponse"}},"hasNext":{"type":"boolean"},"nextCursor":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterCommunicationCursorField"}}},"required":["content","hasNext","cursor"]},"CommCenterCommunicationDetailsResponse":{"type":"object","discriminator":{"propertyName":"channel","mapping":{"phone":"#/components/schemas/CommCenterSmsCommunicationResponse","email":"#/components/schemas/CommCenterEmailCommunicationResponse","chat":"#/components/schemas/CommCenterChatCommunicationResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsCommunicationResponse"},{"$ref":"#/components/schemas/CommCenterEmailCommunicationResponse"},{"$ref":"#/components/schemas/CommCenterChatCommunicationResponse"}],"properties":{"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"}}},"CommCenterSmsCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"},{"type":"object","properties":{"patientContactPhoneNumber":{"type":"string"},"instancePhoneNumber":{"type":"string"},"instancePhoneId":{"type":"string","format":"uuid"}}}]},"CommCenterCommunicationResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"status":{"$ref":"#/components/schemas/CommCenterCommunicationStatus"},"category":{"$ref":"#/components/schemas/CommCenterCommunicationCategory"},"lastMessage":{"$ref":"#/components/schemas/CommCenterLastMessageResponse"},"patientContact":{"$ref":"#/components/schemas/CommCenterPatientContactResponse"},"assignee":{"$ref":"#/components/schemas/CommCenterUserResponse"},"events":{"type":"array","items":{"$ref":"#/components/schemas/CommCenterCommunicationEventResponse"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastPatientContactMessageDate":{"type":"string","format":"date-time"}},"required":["id","channel","status","category","lastMessage","createdAt","updatedAt"]},"CommCenterCommunicationChannel":{"type":"string","enum":["phone","email","chat"]},"CommCenterCommunicationStatus":{"type":"string","enum":["open","closed"]},"CommCenterCommunicationCategory":{"type":"string","enum":["unrecognised","recognised"]},"CommCenterLastMessageResponse":{"discriminator":{"propertyName":"subchannel","mapping":{"sms":"#/components/schemas/CommCenterSmsMessageResponse","email":"#/components/schemas/CommCenterEmailMessageResponse","chat":"#/components/schemas/CommCenterChatMessageResponse","voice_call":"#/components/schemas/CommCenterVoiceCallMessageResponse","internal":"#/components/schemas/CommCenterInternalMessageResponse"}},"oneOf":[{"$ref":"#/components/schemas/CommCenterSmsMessageResponse"},{"$ref":"#/components/schemas/CommCenterEmailMessageResponse"},{"$ref":"#/components/schemas/CommCenterChatMessageResponse"},{"$ref":"#/components/schemas/CommCenterVoiceCallMessageResponse"},{"$ref":"#/components/schemas/CommCenterInternalMessageResponse"}],"properties":{"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"}}},"CommCenterSmsMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"},"deliveryStatus":{"type":"string"},"errorMessage":{"type":"string"}},"required":["message","deliveryStatus"]}]},"CommCenterBaseMessageResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"$ref":"#/components/schemas/CommCenterCommunicationChannel"},"subchannel":{"$ref":"#/components/schemas/CommCenterCommunicationSubchannel"},"direction":{"$ref":"#/components/schemas/CommCenterMessageDirection"},"senderType":{"$ref":"#/components/schemas/CommCenterMessageSenderType"},"user":{"$ref":"#/components/schemas/CommCenterUserResponse"},"createdAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"$ref":"#/components/schemas/CommCenterCreatedBy"},"updatedBy":{"$ref":"#/components/schemas/CommCenterUpdatedBy"},"externalReferenceId":{"type":"string"}},"required":["id","channel","subchannel","direction","senderType","createdAt","updatedAt"]},"CommCenterCommunicationSubchannel":{"type":"string","enum":["sms","voice_call","email","chat","internal"]},"CommCenterMessageDirection":{"type":"string","enum":["incoming","outgoing"]},"CommCenterMessageSenderType":{"type":"string","enum":["patient","contact","unrecognised","user","api_client","system"]},"CommCenterUserResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"enabled":{"type":"boolean"}},"required":["id","firstName","lastName"]},"CommCenterCreatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"}}},"CommCenterUpdatedBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"},"email":{"type":"string"}}},"CommCenterEmailMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"deliveryStatus":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"bodyType":{"$ref":"#/components/schemas/CommCenterEmailBodyType"},"secure":{"type":"boolean"},"starred":{"type":"boolean"},"emailFrom":{"type":"string"},"emailTo":{"type":"string"},"errorMessage":{"type":"string"}}}]},"CommCenterEmailBodyType":{"type":"string","enum":["plain_text","html"]},"CommCenterChatMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterVoiceCallMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"userPhone":{"type":"string"},"childCallStatus":{"type":"string"},"parentCallStatus":{"type":"string"},"recordingDuration":{"type":"integer"},"recording":{"$ref":"#/components/schemas/CommCenterRecordingFileResponse"}},"required":["parentCallStatus"]}]},"CommCenterRecordingFileResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"sizeInBytes":{"type":"integer","format":"int64"},"contentType":{"type":"string"},"url":{"type":"string"}}},"CommCenterInternalMessageResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseMessageResponse"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]},"CommCenterPatientContactResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string"},"phoneNumber":{"type":"string"},"secondaryPhoneNumber":{"type":"string"},"relation":{"type":"string"},"email":{"type":"string"},"secondaryEmail":{"type":"string"},"deleted":{"type":"boolean"},"type":{"$ref":"#/components/schemas/CommCenterPatientContactType"},"pointOfContact":{"$ref":"#/components/schemas/CommCenterPointOfContactResponse"},"sourcePatient":{"$ref":"#/components/schemas/CommCenterPatientContactResponse"}},"required":["id","firstName","lastName"]},"CommCenterPatientContactType":{"type":"string","enum":["patient","contact"]},"CommCenterPointOfContactResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}},"CommCenterCommunicationEventResponse":{"anyOf":[{"$ref":"#/components/schemas/CommCenterPatientContactUpdatedCommunicationEventResponse"}]},"CommCenterPatientContactUpdatedCommunicationEventResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterBaseCommunicationEvent"},{"type":"object","properties":{"oldValue":{"type":"string"},"newValue":{"type":"string"}}}]},"CommCenterBaseCommunicationEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CommCenterCommunicationEventType"},"timestamp":{"type":"string","format":"date-time"}}},"CommCenterCommunicationEventType":{"type":"string","enum":["patient_contact_phone_number_changed","patient_contact_email_changed"]},"CommCenterEmailCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"},{"type":"object","properties":{"patientContactEmail":{"type":"string"},"userEmail":{"type":"string"},"lastEmailSubject":{"type":"string"}}}]},"CommCenterChatCommunicationResponse":{"allOf":[{"$ref":"#/components/schemas/CommCenterCommunicationResponse"}]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/comm-center/users/{userId}/inboxes/{category}":{"post":{"tags":["Communication API"],"summary":"Query user inbox by category","operationId":"CommCenter_Query_inbox","description":"Returns a page of communications from the user's inbox for the given category.","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"userId","in":"path","schema":{"type":"string"},"required":true},{"name":"category","in":"path","required":true,"description":"Allowed values are 'personal', 'care-team', 'all', 'sent'","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommCenterInboxRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommCenterCommunicationWindowResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.welkinhealth.com/api-reference/communication-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.