External Bot Lifecycle

We saw on External Bots a high-level view of a typical chat involving an external bot and where the external bot fits within the overall chat timeline.

Now we'll dig into a more detailed look at the lifecycle of an external bot execution, from the perspective of the external bot.

Scenario: Appointment Scheduling

For the remainder of this guide we'll use a fictitious example Appointment Scheduling Bot to demonstrate the concepts.

Our Appointment Scheduling Bot will be implemented as a MedChat bot, but it will need to execute an external bot to interact with a client-owned external system that manages patient appointments.

Basic Flow

1. Patient starts a chat to schedule an appointment.
2. MedChat bot prompts the patient for identifying information (like last name, SSN last 4, and birthdate).
3. Patient enters their information.
4. MedChat bot stores the patient's input in LastName, SSNLast4, and Birthdate chat attributes.
5. MedChat bot executes the external bot, passing "ExternalScheduler" as the flow identifier.
6. External bot retrieves the LastName, SSNLast4 and Birthdate attribute values and looks up the patient.
7. External bot retrieves the three top available appointment times from the external system.
8. External bot prompts the patient to select one appointment time from the three options.
9. Patient selects the preferred time.
10. External bot reserves the appointment for the patient in the external system.
11. External bot sets a SpecialInstructions chat attribute with any appointment special instructions for the patient.
12. External bot returns control to the MedChat bot.
13. If the external bot failed to schedule the appointment (indicated by a "NotScheduled" returnValue on the Resume Chatbot Execution API call), the MedChat bot transfers the chat to an agent.
14. If the external bot was successful in scheduling the appointment (indicated by a "Scheduled" returnValue on the Resume Chatbot Execution API call), MedChat bot posts a message to the patient indicating that the appointment was successfully scheduled, and includes the SpecialInstructions if provided.
15. MedChat bot ends the chat.

External Bot Lifecycle

The external bot's lifecycle for a given chat is encapsulated in the Execute external bot step shown above.

External Bot Initialization

The external bot begins its work when it receives an ExternalBotFlowTriggered webhook event.

If the external bot needs any data from the chat that has been stored as chat attributes, any submitted user inputs, or other chat-related metadata, it calls the Get Chat Context API endpoint to retrieve those values.

External Bot Execution

The external bot can do as little or as much work as is needed to accomplish its task(s), and the MedChat bot remains paused while the external bot carries out its work.

Often this involves looking up data in external systems, posting messages to and receiving input from the patient, and possibly setting a chat attribute or two.

External Bot Completion

When the external bot is finished with its work, it finishes up by calling the Resume Chatbot Execution API endpoint, passing it any returnValues that the calling MedChat bot might need.

Alternate Flows

We've outlined the "happy path" of the bot above, but things don't always go according to plan. You'll need to handle unexpected inputs, patient not found exceptions, and failures when reserving the appointment, according to your requirements.

It's also possible that the patient might close the MedChat widget, ending the chat in the middle of the bot execution. If your service subscribes to the ChatEnded webhook event, it can take appropriate action when a chat that is in the middle of an external bot execution ends prematurely.

📘

See Webhook Management for more details on the ExternalBotFlowTriggered, ChatContextUpdated, and ChatEnded events.