Key Concepts

To be successful in creating your external bot, you'll need to understand a few key concepts. We'll introduce them here and go into more detail when we talk specifics about how to build your bot.

External Bot Architecture

How should you architect your external bot service?

That's completely up to you (and possibly the team you're working on)!

The only requirement from MedChat's perspective is that your service is capable of...

1. receiving HTTP webhook requests, and
2. making API calls into the MedChat API.

📘

External bot or external bot service?

For the purposes of this guide, we'll use the term "external bot" as shorthand to refer to the external bot service that receives webhook events from MedChat and makes API calls to the MedChat API.

Sending and Receiving Data

In order to do anything meaningful, your external bot will need to receive data from MedChat and send data to MedChat.

Receiving Data

MedChat pushes data to your external bot using webhook events. A webhook event notifies your service that something happened with one of your organization's chats.

See the Webhooks guide to get started receiving webhook events.

You can subscribe to specific events specifying an endpoint on your service, and MedChat will call that endpoint whenever the event occurs.

Webhook Management describes the categories of events you can listen for, but the ones that will be of particular interest to you when building your external bot will probably be the following:

• External Bots Events
• Chat Context Events
• Chat Status Events

Sending Data

Your external bot sends data to MedChat by making authenticated calls to the MedChat API. To do this, you'll first need to obtain an authorization token, as described in API Authentication.

Once you have an authorization token, you can make calls to the MedChat API using any of the endpoints described in the API Reference.

You'll call the API to do things like...

• Post a message to the patient.
• Get the chat context.
• Create or update a chat attribute.
• Resume execution of the MedChat bot.

🚧

Note that there are many MedChat API endpoints available that are intended for non-external bot applications and probably won't make sense to call from your external bot.

We cover the most common endpoints that you'll likely need to use in this guide.

Key Identifiers

There are a couple of key identifiers that will be included on every webhook event that you receive from MedChat and on every request that you make into the MedChat API.

• orgId - Unique identifier for your organization, which can be found on the Developer > API screen in MedChat.
• chatId - Unique identifier for a specific chat.

Your external bot first learns of a new chatId (and its corresponding executionId, which will be needed to resume the MedChat bot execution when your external bot has completed its work) when it receives an ExternalBotFlowTriggered webhook event.

📘

It's likely that you'll want to store the key identifiers for a chat in a database table when an ExternalBotFlowTriggered event is received, so that you can keep track of the state of the chat and correlate future events with their associated chat.

Chat Context

A chat's context is a data structure that contains several collections of data about a particular chat.

• Chat Properties - Client-defined properties passed when the chat was started
• Chat Attributes - Attributes set during the course of chatbot execution
• User Inputs - Inputs provided for forms and/or chat bot questions
• Metadata - Metadata associated with the chat

The ChatContextUpdated webhook event fires when the chat context changes. You can also retrieve the current chat context at any time via the Get chat context API call.

Message Context

Similar to the chat context, the message context contains data about a particular message.

• User Inputs - Input(s) provided on forms and/or chatbot question message responses
• Metadata - Metadata associated with the message

You can call the Get message context API endpoint to get a patient's response to a chatbot question.