Chat

Search: start pagination

get

Let assume that we have the following chat (messages in the list are sorted from older to newest):

Hello0
Hello1
Test1
Test2
Hello2
Test3
Test4

So let’s search by query “Hello”. Assume pageSize=2 and contentPageSize=1 and make the following request

HTTP Method: GET
HTTP URL: https://api.live.welkincloud.io/gh/sb-demo/patient/7272b601-bb09-4abf-87c0-ade48ddfaea0/chat/search?query=hello&pageSize=2&contentPageSize=1&includeArchived=true

As you can see, two messages are found: the first is “Hello2” and the second is “Hello1”. “content” length is limited to pageSize, so to fetch next messages that matches query you should use pass “meta.nextPageToken” as pageToken.

Authorizations

AuthorizationstringRequired

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

Path parameters

tenantNamestringRequired

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

Example: acme-health

instanceNamestringRequired

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

Example: live

patientIdstring · uuidRequired

UUID of the patient record

Query parameters

querystringOptional

Query for search

Example: hello

pageSizeintegerOptional

How many search results per page will returns

Default: 20Example: 2

contentPageSizestringOptional

How many messages per page will return get messages api when you'll pass content.meta.nextPageToken or content.meta.prevPageToken as pageToken param to that api

Example: 2

includeArchivedbooleanOptional

If true, include archived messages, otherwise not.

Example: true

pageTokenstringOptional

Token for fetching next or previous search results. Mutually exclusive with query/pageSize/contentPageSize.

Responses

200

Paginated chat search results (fresh page via query, or resume via pageToken)

application/json

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/patients/{patientId}/chat/search

GET /{tenantName}/{instanceName}/patients/{patientId}/chat/search HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "meta": {
    "nextPageToken": "text",
    "prevPageToken": "text",
    "isFound": true,
    "pageSize": 1
  },
  "content": [
    {
      "meta": {
        "nextPageToken": "text",
        "prevPageToken": "text"
      },
      "message": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "sender": {
          "clientType": "CS_TOOL_CLIENT",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "titleName": "text",
          "patientFullName": "text"
        },
        "receiver": {
          "clientType": "CS_TOOL_CLIENT",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "titleName": "text",
          "patientFullName": "text"
        },
        "message": "text",
        "externalId": "text",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "attachments": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "originalName": "text",
            "size": 1,
            "contentType": "text",
            "storageKey": "text"
          }
        ],
        "skipEvent": true,
        "deletedAt": "2026-01-01T00:00:00.000Z"
      }
    }
  ]
}

Chat: Send message from patient to care team

post

Send message from patient to care team.

URL Structure: {{url}} / {{tenantName}} / {{instanceName}} / patients / {{patientId}} / chat / inbound

in our example it would be:

https://api.live.welkincloud.io/gh/sb-demo/patients/7272b601-bb09-4abf-87c0-ade48ddfaea0/chat/inbound

Supported file extensions: jpg,mp3,pdf,png,jpeg,wav,ogg

Authorizations

AuthorizationstringRequired

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

Path parameters

tenantNamestringRequired

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

Example: acme-health

instanceNamestringRequired

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

Example: live

patientIdstring · uuidRequired

UUID of the patient record

Body

Either message or an attached file is required.

messagestringOptional

attachmentAsFilesstring · binary[]Optional

Supported extensions: jpg, mp3, pdf, png, jpeg, wav, ogg.

Responses

201

Message sent

application/json

idstring · uuidRead-onlyOptional

messagestringOptional

Required if attachmentAsFiles is empty.

externalIdstring · nullableOptional

createdAtstring · date-timeRead-onlyOptional

skipEventbooleanOptional

deletedAtstring · date-time · nullableRead-onlyOptional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

post/{tenantName}/{instanceName}/patients/{patientId}/chat/inbound

POST /{tenantName}/{instanceName}/patients/{patientId}/chat/inbound HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 49

{
  "message": "text",
  "attachmentAsFiles": [
    "binary"
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sender": {
    "clientType": "CS_TOOL_CLIENT",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "titleName": "text",
    "patientFullName": "text"
  },
  "receiver": {
    "clientType": "CS_TOOL_CLIENT",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "titleName": "text",
    "patientFullName": "text"
  },
  "message": "text",
  "externalId": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "attachments": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "originalName": "text",
      "size": 1,
      "contentType": "text",
      "storageKey": "text"
    }
  ],
  "skipEvent": true,
  "deletedAt": "2026-01-01T00:00:00.000Z"
}

Get Messages

get

Endpoint: GET {{url}}/{{tenantName}}/{{instanceName}}/patients/{{patientId}}/chat

Description: This endpoint retrieves the chat history for a specific patient. It allows you to view the conversation or messages exchanged between the patient and the healthcare provider or system.

URL Parameters:

{{url}}: The base URL of the API.
{{tenantName}}: The name or identifier of the tenant within the system.
{{instanceName}}: The name or identifier of the specific instance within the tenant.
{{patientId}}: The unique identifier of the patient for whom the chat history is being requested.

HTTP Method: GET

Authorization: This endpoint may require authentication and authorization based on the system's security policies. Valid credentials or access tokens may be required to access the chat history.

Response: The response from this endpoint will typically be in JSON format and will contain the chat history for the specified patient. The exact structure of the response may vary based on the system's implementation. It may include details such as timestamps, sender information, and message content.

Example Request: GET {{url}}/{{tenantName}}/{{instanceName}}/patients/123456/chat

Example Response:

jsonCopy code{
  "patientId": "123456",
  "chatHistory": [
    {
      "timestamp": "2023-06-08T10:30:00Z",
      "sender": "Healthcare Provider",
      "message": "Hello, how can I assist you today?"
    },
    {
      "timestamp": "2023-06-08T10:32:00Z",
      "sender": "Patient",
      "message": "I'm experiencing some chest pain."
    },
    {
      "timestamp": "2023-06-08T10:35:00Z",
      "sender": "Healthcare Provider",
      "message": "I recommend scheduling an appointment for further evaluation. Can you come in tomorrow?"
    },
    {
      "timestamp": "2023-06-08T10:37:00Z",
      "sender": "Patient",
      "message": "Yes, tomorrow works for me. What time?"
    }
  ]
}

Note: The above example response is for illustrative purposes only and may not reflect the actual response format of the system.

Error Handling: In case of errors, the endpoint may return appropriate HTTP status codes along with error messages or error objects to indicate the failure reason. Common status codes include 4xx for client errors (e.g., invalid parameters) and 5xx for server errors (e.g., internal server error).

Security Considerations: To ensure the privacy and security of patient information, proper authentication and authorization mechanisms should be implemented for accessing this endpoint. Access to patient chat history should be restricted to authorized personnel only.

Rate Limiting: To prevent abuse or overload on the system, rate limiting mechanisms may be applied to this endpoint. Clients may need to adhere to certain limits on the number of requests per time period.

Note: Replace the placeholder variables (e.g., {{url}}, {{tenantName}}, {{instanceName}}, {{patientId}}) with actual values specific to your system implementation.

Note: Received links to attachements expires in 5 minutes. You can refresh them by the endpoint ' Get File by fileId'.

Authorizations

AuthorizationstringRequired

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

Path parameters

tenantNamestringRequired

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

Example: acme-health

instanceNamestringRequired

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

Example: live

patientIdstring · uuidRequired

UUID of the patient record

Query parameters

pageTokenstringOptional

Token for fetching a specific page. Mutually exclusive with pageSize.

includeArchivedbooleanOptional

If true, include archived messages in the result.

Example: true

sizeintegerOptional

Page size. Mutually exclusive with pageToken.

Example: 10

Responses

200

Paginated chat messages (fresh page, or resume via pageToken)

application/json

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/patients/{patientId}/chat

GET /{tenantName}/{instanceName}/patients/{patientId}/chat HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "meta": {
    "nextPageToken": "text",
    "prevPageToken": "text",
    "isFound": true,
    "pageSize": 1
  },
  "content": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "sender": {
        "clientType": "CS_TOOL_CLIENT",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "titleName": "text",
        "patientFullName": "text"
      },
      "receiver": {
        "clientType": "CS_TOOL_CLIENT",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "titleName": "text",
        "patientFullName": "text"
      },
      "message": "text",
      "externalId": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "attachments": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "originalName": "text",
          "size": 1,
          "contentType": "text",
          "storageKey": "text"
        }
      ],
      "skipEvent": true,
      "deletedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Get File by fileId

get

Endpoint: GET {{url}}/{{tenantName}}/{{instanceName}}/files/:fileId

Description: A file refresh endpoint is required to renew an expired link to a file. The endpoint should accept a fileID as a parameter in order to proceed.

URL Parameters:

{{url}}: The base URL of the API.
{{tenantName}}: The name or identifier of the tenant within the system.
{{instanceName}}: The name or identifier of the specific instance within the tenant.
:fileId: The unique identifier of the file being requested. This parameter should be replaced with the actual fileId value.

HTTP Method: GET

Authorization: Depending on the system's security policies, this endpoint may require authentication and authorization. Valid credentials or access tokens may be required to access and download the file.

Response: The response from this endpoint will typically contain the requested file or the necessary information to retrieve the file. The exact structure of the response may depend on the system's implementation. If the file is available, the response may include the file content or a link to download the file.

Example Request: GET {{url}}/{{tenantName}}/{{instanceName}}/files/123456

Example Response (File Content): The response can vary based on the file type and system implementation. For binary files, the response might include the file content as raw bytes.

Example Response (File Download Link):

jsonCopy code{
  "fileId": "123456",
  "fileName": "example.pdf",
  "downloadLink": "https://example.com/downloads/123456"
}

Note: The above example response is for illustrative purposes only and may not reflect the actual response format of the system.

Error Handling: In case of errors, the endpoint may return appropriate HTTP status codes along with error messages or error objects to indicate the failure reason. Common status codes include 4xx for client errors (e.g., invalid fileId) and 5xx for server errors (e.g., internal server error).

Security Considerations: To ensure the security and privacy of files, proper authentication and authorization mechanisms should be implemented for accessing this endpoint. Access to files may need to be restricted based on user roles and permissions.

Note: Replace the placeholder variables (e.g., {{url}}, {{tenantName}}, {{instanceName}}, :fileId) with actual values specific to your system implementation.

Authorizations

AuthorizationstringRequired

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

Path parameters

tenantNamestringRequired

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

Example: acme-health

instanceNamestringRequired

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

Example: live

fileIdstring · uuidRequired

UUID of the uploaded file

Responses

200

File metadata with a signed, time-limited download URL

application/json

idstring · uuidOptional

originalNamestringOptional

sizeintegerOptional

Bytes

contentTypestringOptional

storageKeystringOptional

urlstring · uriOptional

thumbnailUrlstring · uri · nullableOptional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/files/{fileId}

GET /{tenantName}/{instanceName}/files/{fileId} HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "originalName": "text",
  "size": 1,
  "contentType": "text",
  "storageKey": "text",
  "url": "https://example.com",
  "thumbnailUrl": "https://example.com"
}

PreviousEmail

NextCare Plan

Last updated 18 days ago

Was this helpful?