Call an external system from a bot

Call External API contacts another system while the conversation is running, and saves what comes back for later steps to use. Use it when the answer lives somewhere else — an order in your own system, a balance, a booking reference.

Availability and setup

• Plan entitlement: Enterprise.
• Setup responsibility: Qcom-assisted. A Qcom platform administrator configures the step; workspace members cannot add it themselves.
• Credential responsibility: Your workspace supplies the endpoint and required authentication. Qcom stores credentials as workspace secrets outside the bot builder.
• Runtime: The request runs from a published bot. Flow preview does not call the endpoint.
• Direction: Qcom sends an outbound HTTPS request to your external system. This step does not provide an endpoint for sending events into Qcom.

Before you start

Have the endpoint's URL, its method, and any credentials it needs. Credentials are stored as workspace secrets and referenced as {{secrets.key_name}} — never pasted into the step, where they would be visible to anyone who can open the bot.

The endpoint must be HTTPS.

Set it up

1. Add Call External API to the canvas and select it.
2. Choose the HTTP Method — GET, POST, PUT or DELETE.
3. Enter the URL. It can include {{variable}} to pass answers from the conversation, and {{secrets.key_name}} for credentials.
4. Add Headers (JSON) if the endpoint needs them, as a JSON object.
5. For POST and PUT, add the Request body (JSON).
6. Set Save response as so later steps can read the result.
7. Set the Timeout (seconds). The maximum is 30.

Choose a timeout that gives the service time to respond without leaving the customer waiting too long. Write a useful failure reply for when that wait ends.

Connect the routes

The step has two routes, and both must be connected:

• On Success — the call returned successfully. Continue with the response.
• On Failure — the call failed, timed out, or returned an error.

Connect On Failure to a short explanation and a way forward, such as a handoff or follow-up. Do not put the external system's raw error response in the customer message.

A timeout does not prove the other system made no change. If the call creates, updates or deletes something, check its result there before repeating it. Do not connect every failure straight back to the same call.

Use the response

The saved response holds what the endpoint returned. Refer to it in later steps the same way as any other saved value, with {{ }}.

Check the response before claiming the customer's task is complete. A successful call is not necessarily a completed booking, payment or other business outcome. The failure route can also have a saved response; its presence alone does not prove success.

If the response is a list, Dynamic List can turn it into choices the customer picks from.

Common problems

A step marked Incomplete cannot be used in a published bot. Select the incomplete step and the settings panel shows what must be fixed.

Here, the usual causes are:

• Either route left unconnected
• Headers (JSON) or Request body (JSON) that is not valid JSON
• A URL that is not HTTPS

For repeated failures, ask the person managing the integration to check the saved secret, destination, service availability and response. A missing secret is one possible cause, not the only one. Keep diagnostic details out of customer messages.

Test it

Use Flow preview to walk both routes. Flow preview does not send any messages and does not contact any customer.

The preview does not call the real endpoint, so test the endpoint separately before publishing.

Related

• Show a list built from your own data
• Hand a conversation over to a person
• Build a bot on the canvas