Now that we've introduced the Get Chats API, let's walk through the process of configuring an external system to retrieve chat files via the Medchat API.

Scenario: An organization has a chatbot that collects insurance information and prompts the patient to upload a picture of their insurance card. When the chat completes, the organization needs to automatically retrieve the insurance information that was entered and retrieve the image file that was uploaded, for storage in their system.

🚧

Your implementation may vary!

While this guide will be as specific as possible as far as what is happening on the Medchat side of the service boundary, please note that your implementation will vary depending on the details of how your service is structured and implemented.

Broadly speaking the steps to accomplish this will be the following:

1. Create access token.
2. Set up webhook.
3. Retrieve chat by ID.
4. Process chat messages.
5. Retrieve chat file by ID.

Create Access Token

The first step is to create an access token that will be used to call into the Medchat API from the external system.

Follow the instructions in the API Authentication guide to create your access token. For this example scenario, the access token would need the read.my_orgs.chats scope.

Set Up Webhook

Next, you'll need to create a webhook that will notify the external system whenever a chat completes. This will be the trigger for the external system to call into the Medchat API to retrieve the relevant data.

Follow the instructions in the Webhooks guide to create a webhook that will fire whenever a chat on the desired widget and topic ends. In order to receive webhook events, an API endpoint in the external system will need to be created and made available that can respond to Webhook Endpoint Verification challenges successfully and handle webhook events.

For this example scenario, you'll want to create a Chat Status webhook event, filtered by Widget, Topic, and Event Type = "ChatEnded".

Retrieve Chat by ID

📘

The rest of the steps in this walkthrough will occur within the webhook event handler in the external system.

Specific webhook event handler implementations will vary depending on the technical details of the external system. This guide will speak to the specific integration points with the Medchat API, while speaking in general terms regarding the event handler in the external system.

Upon receiving a "ChatEnded" webhook event, you'll call into the Medchat API Get chat by ID endpoint to retrieve the chat data for the chat by orgId and chatId received in the event payload:

GET https://api.medchatapp.com/orgs/{orgId}/chats/{chatId}?$expand=Messages

Request Headers -
Accept: application/vnd.medchat+json;v=2.0
Authorization: Bearer {your_access_token}

The payload of a successful response will be a chat object that conforms to the model described in the 200 Response section of the Get chat by ID doc.

Process Chat Messages

Upon successfully retrieving a chat object, your event handler will need to iterate over the messages array and determine which messages are relevant to process. If a chatbot was involved, the messages should be somewhat predictable in that they will follow the chatbot flow, and message blocks will have IDs that match message block IDs set in the chatbot builder.

Note that the message body is an array of one or more message blocks. Each message block is one of several concrete types, defined in the Message Blocks guide.

For the sake of our example, assume the chatbot has a step that prompts the user for health insurance details with multiple inputs. The step has a text input message block with the ID MemberId and a file upload message block with the ID InsuranceCardImage.

The event handler will iterate over the messages and identify the message where the chatbot prompted the patient for health insurance details - this is the request message. The handler will then find a SubmittedFormMessageBlock (see submitted forms) in the array of messages with a RequestMessageId that matches the Id of the request message. This message contains the patient's responses in the ReadOnlyForm message block array. The message body will resemble the following:

[
    {
        "id": "<generated ID>",
        "type": "SubmittedFormMessageBlock",
        "requestMessageId": "<original message ID>",
        "readOnlyForm": [
            {
                "id": "MemberId",
                "type": "SubmittedInputMessageBlock",
                "label": "What is your member ID?",
                "values": [
                    "B123-11135"
                ],
                "isPrivate": false,
                "inputMessageBlockConfig": {
                    "type": "SimpleInputMessageBlockConfig",
                    "inputMessageBlockType": "TextInputMessageBlock"
                }
            },
            {
                "id": "InsuranceCardImage",
                "type": "SubmittedInputMessageBlock",
                "label": "Upload an image of your insurance card:",
                "values": [
                    "<chatFileId>"
                ],
                "isPrivate": false,
                "inputMessageBlockConfig": {
                    "type": "SimpleInputMessageBlockConfig",
                    "inputMessageBlockType": "FileUploadInputMessageBlock"
                }
            }
        ]
    }
]

The event handler will parse the readOnlyForm, extracting the values from the submitted input message blocks and persisting them as desired.

Retrieve Chat File By ID

To retrieve the file that was uploaded, the event handler uses the chat file ID from the InsuranceCardImage SubmittedInputMessageBlock to request the file from the Medchat API Get chat file endpoint:

GET https://api.medchatapp.com/orgs/{orgId}/chats/{chatId}/files/{chatFileId}

Request Headers -
Accept: application/vnd.medchat+json;v=2.0
Authorization: Bearer {your_access_token}

The response will return the contents of the file as a binary stream that can be saved in the external system.