HTTP

What it does#

The HTTP step calls a URL while the chat is running: your CRM, your store, an Airtable base, a Make or Zapier webhook. It can send the customer's answers, and read the answer back into variables that later steps use, for example the order status or the customer's name.

The customer doesn't see this step. When the call is done, the chat continues to the next step.

Not sure whether you need HTTP or Catch Hook? HTTP is Officely calling your system. Catch Hook is your system calling Officely.

Set up a call#

1. 1

   Drag HTTP onto the canvas

   It's under Webhook and API in the step list. Connect the step before it, then click the step to open its settings.

2. 2

   Pick the method and URL

   In the Request tab, choose the Method (GET, POST, PUT, PATCH, DELETE or HEAD) and type the URL. It must start with https:// (or http://). Optionally, describe the call in What this call does so your team knows what it's for.

3. 3

   Add query parameters (optional)

   Under Query parameters, click Add parameter. They're added after ? in the URL and encoded for you.

4. 4

   Set up Auth

   Open Auth and pick None, Bearer token, Basic or API key. Use a secret instead of pasting the key itself.

5. 5

   Add headers (optional)

   In Headers, click Add header, for example Accept = application/json.

6. 6

   Write the body

   In Body, choose None, JSON, Form or Raw text. Type @ or # to insert a variable, or use the variable button { } at the end of any field.

7. 7

   Save what comes back

   In Response, pick the fields you need and give each one a variable name. The easiest way: run a Test call and click the fields.

8. 8

   Decide what happens on failure

   In Errors & retries, turn on Continue on the Error output when the call fails and connect the red Error output on the canvas.

9. 9

   Test it

   Open Test, fill in sample values and click Test call.

Prefer to start from a working example? Use Start from a template at the top of the Request tab: Send to Make webhook, Airtable: find records, Google Sheets (Apps Script) webhook or Generic REST GET. Replace the parts in capitals with your own IDs, then run a Test call.

If the service's API docs (or Postman) give you a curl command, click Import from cURL, paste it and click Read command, then Import. The method, URL, headers and body fill in for you. If the command contains a key, you're offered to save it as a secret. File uploads (-F) can't be imported.

The body#

For JSON and Form you can also tick:

• Include all answers: adds every answer the customer gave so far, by step name.
• Include all data (as "data") (JSON only): adds all the conversation's data, for example what a Catch Hook sent, under data.
• Add cphone and isPreview: adds the customer's phone (cphone) and whether this is a preview chat (isPreview).

In JSON, a value that is only one variable keeps its type. "{{#order.total}}" sends the number 84.5, not the text "84.5". The same goes for true / false and lists.

{
  "name": "{{@full_name}}",
  "phone": "{{#cphone}}",
  "interest": "{{@service}}",
  "source": "whatsapp-bot"
}

HEAD calls never send a body.

Save the response as variables#

Any method can save its answer, POST included. Open the Response tab:

• Save fields as variables: each row is a field path on the left, like data.user.name or items[0].id, and a variable name on the right, like userName. Later steps use {{#userName}}. Click Add field for more rows (up to 30).
• Save the whole answer: type a name in Save response as, for example order. Later steps use {{#order.status}}, {{#order.items[0].sku}} and so on. To keep only one part, add a path in Save only (optional), for example data.items.
• Also add the answer's data fields as variables (the classic GET behaviour): merges the answer's data object (or the whole answer, if there is no data) straight into the variables, so {"data": {"status": "shipped"}} becomes {{#status}}.

In the Test tab, click { } next to any field of the answer to add it to Save fields as variables in one click. Rename it in the Response tab if you like.

In the full editor, the status code of the last call is also saved as {{#http_status}}.

Errors & retries#

By default, if the call fails, the chat stops at this step. Turn on Continue on the Error output when the call fails and the step gets a red Error output. Connect it, for example, to a message that says "We couldn't load your order right now. A team member will get back to you."

These go to the Error output: network errors, timeouts, any status that isn't 2xx, an answer that isn't JSON when you save fields, and a missing secret. On the Error output you can use:

• Timeout (seconds): 1 to 30. Leave it empty to keep the default (60 seconds). A timeout counts as an error.
• Retries: 0 to 3. The call is tried again after a network error, a timeout, a 5xx or a 429, with growing pauses, all within about 20 seconds so the customer isn't kept waiting.
• GET, HEAD, PUT and DELETE are retried. POST and PATCH are retried only if you tick Safe to repeat this POST (it doesn't create anything twice).

Outputs by status code gives some answers their own output. Click Add output, enter a status (or a range like 400 to 499) and a name, for example 404 = Not found. They're checked before Success and Error. Up to 5.

Keep keys in secrets#

Never paste an API key straight into a step: anyone who can open the bot can read it. Save it as a secret instead and write {{secret.NAME}} where the key goes.

1. 1

   Open Manage secrets

   In the Auth tab, click Manage secrets.

2. 2

   Name it

   Type a name such as CRM_TOKEN (letters, digits and _, starting with a letter).

3. 3

   Paste the value

   Paste the key in Value. It's never shown again after you save.

4. 4

   Set the allowed hosts

   In Allowed hosts, list where this secret may be sent, for example api.crm.com or *.crm.com. It's filled with the URL's host for you.

5. 5

   Save and use it

   Click Save secret. Then pick it from the variable button { } in Auth, a header, a query value or the URL, for example Authorization: Bearer {{secret.CRM_TOKEN}}.

• A secret is only sent to its allowed hosts. Calling another host fails with a message that names the secret.
• Secrets work in the URL, query, headers and Auth, not in the body.
• Only the account owner or an admin can save or delete secrets. Everyone who edits bots sees the names and hosts.
• An account can have up to 50 secrets.

Test a call#

The Test tab runs the call for real, right now. It lists every variable the call uses: fill in a sample value for each, then click Test call.

You see the status, how long it took, the answer's headers and the answer itself. Click { } next to a field to save it as a variable. Copy as cURL copies the request for a terminal: secrets stay as {{secret.NAME}}, so fill them in yourself.

Example: look up an order#

A store bot asks for the order number in a Text step named order_number, then:

1. Request: GET https://api.mystore.com/v1/orders/{{@order_number}}
2. Auth: Bearer token = {{secret.STORE_TOKEN}}
3. Test: sample value 1001, then Test call. The answer is {"data": {"status": "shipped", "eta": "Thursday"}}.
4. Click { } next to data.status and data.eta. In Response, rename them order_status and order_eta.
5. Errors & retries: turn on the Error output, Retries = 2, and add an output 404 = Not found that asks the customer to check the number.

Classic HTTP step#

Accounts without the full editor see the classic fields: Description, URL, the Method (GET or POST) and a JSON body.

• GET loads data. The answer's data field (or the whole answer, if there is no data) becomes variables. An answer {"data": {"status": "shipped"}} gives {{#status}}.
• POST sends the JSON body, plus the customer's phone (cphone) and isPreview. In the classic step, the answer to a POST isn't saved. To use it, save the response in the full editor (see above).

Common mistakes#