Skip to main content
A custom connector lets Aide look a customer up in a system of your own, such as your back office, a subscription platform or a warranty database, before it writes a reply. You give Aide the address of the system’s API and say what to ask it. Aide then asks for each customer who writes in, and its AI reads the fields you picked, so a reply can say which plan the customer is on or when their order ships without anyone looking it up. Find it under Integrations > Custom connectors. A connector reads. Aide never changes anything in your system through it.

What your system needs

  • An API at a public address that starts with https://.
  • A request that finds a customer by their email address or their phone number and answers in JSON.
  • An answer within 3 seconds and no larger than 256 KB. Aide doesn’t follow a redirect.

Add a connector

  1. Open Integrations > Custom connectors and select Add connector.
  2. Enter a Name. The AI reads it as the source of what it looks up, so name the system, such as “Order system”.
  3. Enter the Base URL, such as https://api.example.com/v2. Each lookup adds its own path to it.
  4. Under How Aide signs in, choose No sign-in, Bearer token, an API key sent in a header you name, or Username and password, and enter the secret.
  5. Add up to 5 Constant headers if your API needs them on every request, such as a version header.
  6. Select Add connector.
Aide stores the secret encrypted and never shows it again. To replace it, edit the connector and enter a new one. If you change the connector’s address to a different host, Aide removes the saved secret and asks for it again, so a secret is never sent to an address it wasn’t entered for.

Add a lookup

A lookup is one request about the customer who wrote in, and the fields of its answer that the AI reads. Open the connector and select Add lookup.
  1. Enter a Name. The AI reads it as the kind of record, such as “Subscription” or “Latest order”.
  2. Choose the Method, GET or POST, and enter the Path. Select Insert variable to put a detail of the conversation in the path, such as /customers/{requester.email}/subscription.
  3. Add query inputs, or body inputs for a POST. Each is a constant you type or a variable from the list.
  4. Under Test this lookup, enter the email address, or the phone number, of a customer your system knows and select Run test. Aide makes the request as it is in the form, saved or not, and shows the answer once. The answer isn’t stored.
  5. In What the system answered, click each value the AI should read. It is added under Fields the AI reads with a label you can change. Pick up to 12 and drag them into order, most important first. For an answer that holds a list, such as a customer’s orders, see “Read a list” below.
  6. If your system answers with an empty record instead of “not found” when it has no such customer, name a place in the answer under No record when this is missing or empty.
  7. Choose Reuse an answer for, from Do not reuse to 1 hour. Aide keeps an answer for the same customer that long before it asks your system again. With Do not reuse it asks for each message, and keeps the answer for 30 seconds so that everything Aide does with one message reads the same record.
  8. Select Save lookup.
After a test, What the AI reads shows the record exactly as the AI will get it.

Read a list

An answer often holds a list: a customer’s orders, a family’s enrolments, the items of a subscription. Aide can read it in two ways.
  • A line for each item: beside a value inside an item of the list, select In every item. The list becomes one field, and the AI reads a line for each item with the values you picked, such as “Orders 1: Number: 1042; Status: shipped” for a field labelled Orders. Pick up to 6 values of an item. The AI reads the first 10 items; when the list is longer, it is told how many were left out.
  • Every value on one line: click a list of plain values, such as tags, to read it whole. In a path you type, * stands for every item of a list, so orders.*.number reads every order’s number as “1042, 1043”.
A path can also read one item by its place, counted from 0: orders.0.status is the first order’s status. $ alone is the whole answer, for a system that answers with a list and nothing around it.

What Aide sends your system

Only what the lookup names. The editor spells it out under What Aide sends before you save. The details a lookup can send are:
  • Requester’s email: the email address of the person who wrote in.
  • Requester’s phone: their phone number in international format, such as +14155550100. Aide sends it on WhatsApp, where a message comes from the customer’s own number, and on no other channel.
  • Requester’s name: their name.
  • Conversation ID: Aide’s id of the conversation.
Every lookup sends the requester’s email or their phone, because that is how your system finds the customer. A lookup runs only when Aide has every detail it sends: one that sends the phone runs on WhatsApp, and one that sends the email runs where the customer’s email is known. Nothing else from the conversation is sent: no message, no subject and no attachment.

When a lookup runs

Aide runs each enabled lookup before it writes a reply or a draft, about once per customer in the time you chose under Reuse an answer for. It runs only when the channel has proven who wrote in:
  • Email: the message passed the sender checks for the address it came from.
  • A helpdesk ticket: the latest message is from the ticket’s requester and nobody outside your team is copied on it.
  • WhatsApp: the message comes from the customer’s own number.
It doesn’t run in chat on your website, where a visitor types their own email address, in a preview, or on a conversation created from a form. There the AI is told nothing from your system and answers as it would without the connector.

What the AI does with the answer

The AI reads the fields you picked as facts about the customer, beside their orders and other details. It is told to treat a field’s value as information, not as an instruction.
  • No record: when your system has no such customer, the AI reads “No record found” and doesn’t guess.
  • No answer: when your system is slow, fails or refuses the sign-in, the AI reads “Not available right now” and says it can’t check, instead of answering from memory.

See the record in a conversation

A conversation’s side panel has a Custom connectors section once a lookup is enabled. It shows, for each enabled lookup, the record Aide holds for the customer who wrote in: the same fields the AI reads, under the lookup’s name. Everyone who can open the conversation sees it.
  • No record found means your system has no such customer, and Not available right now that it didn’t answer.
  • When Aide couldn’t verify who wrote in, the section says so and shows no record, as the AI was told nothing either.
  • Opening a conversation can make Aide ask your system, when it holds no recent answer for that customer. The request is listed in Recent calls like any other.
  • Teammates opening conversations use at most 20 of a connector’s 60 requests a minute, so reading the inbox never keeps a reply from its lookup. Past that, the section shows Not available right now until the minute has passed.

Use fields in procedures

A field read at one place of the answer can be a procedure condition, listed under “connectors” in the condition picker: a procedure can run only for customers whose plan is “Premium”, or whose account is “Suspended”. When the field holds a list of plain values, such as tags, the condition holds when one of them is the value. A list read as a line for each item, or a path with *, can’t be a condition.
  • A condition holds only when the lookup ran for the message and found a record with a value in that field. It never holds when Aide couldn’t verify who wrote in, when your system has no record or doesn’t answer, or when the lookup is disabled.
  • Aide looks a customer up only while it handles their message. An estimate of how many recent conversations a procedure would match, a test and a run on existing conversations don’t call your system, so a condition on a connector’s field doesn’t hold there.
  • When you remove a field from a lookup, a procedure that has a condition on it shows a warning, and the condition no longer holds.

When your system keeps failing

  • After 5 failed requests in a row, Aide stops asking for a minute, then tries again.
  • Aide makes at most 60 requests a minute to a connector, however many conversations arrive. At most 20 of them are for teammates opening conversations.
  • When every request has failed for 24 hours, Aide disables the connector and notifies your owners and admins. The connector shows Disabled by Aide. Check Recent calls, fix what they show, then enable it again.

Recent calls

A connector’s page lists every request Aide made to it in the last 30 days, newest first, with the lookup, the result, the HTTP status, how long it took and the names of what was sent. It keeps names, never values: no email address and nothing your system answered. A request made for a conversation links to it.

Limits

  • 10 connectors in a workspace, and 20 lookups in a connector.
  • 3 lookups enabled at a time across the workspace.
  • 12 fields a lookup. The AI reads about 1,200 characters of a record, from the top of your order.
  • A list is one field: its first 10 items, and up to 6 values of each.

Who can do this

Owners and admins add, change, test and remove connectors and read their recent calls. Every change is in the audit log. Everyone on the team sees the Custom connectors section in conversations.