Threadwire by TriTech

← API reference

A menu of choices

An instance can offer the people who write to it a short menu: "1 for prices, 2 for opening hours, 3 to talk to someone". They answer with a digit, and the instance sends what you set for it. There is no code to write and no diagram to draw: a greeting, up to nine choices, and what each one does.

Set it up in your panel under Auto-replies → Menu, where you see exactly what people will receive and can send it to yourself first. Or use the API below.

Every message of the menu is an ordinary reply from the instance, with the same protection as any message: "typing…" first, the reply's pace, and every limit. It never writes first to anyone.

What a choice can do

  • Send an answer: words you write, or one of your team's saved answers. A saved answer is read when it is sent, so editing it once changes the menu too.
  • Open a sub-menu: one level deep. A choice inside a sub-menu answers or hands over; it cannot open another menu. Inside a sub-menu, 0 goes back to the first menu.
  • Hand over to a person: the person is told so in your words ("Someone from our team will answer you here."), and the chat waits under "Needs a reply" in Chats. You may also put a label on the chat and give it to a teammate. A chat a teammate already looks after stays with them.

How people choose

  • The digit alone: 2, or ٢. Spaces or a full stop around it do not matter, and people may use either kind of digit whichever your menu shows.
  • Or the choice's own words, as the whole message: "Opening hours".
  • Anything else is not a choice: "2 please", "12", a photo. The menu is then shown again, but not for what the person wrote before the menu reached them or within a minute of it: several messages in a row get one menu.
  • A menu stays open for 4 hours after it was sent. After that, whatever the person writes gets the first menu again. The same happens when you change the menu.

When it answers, and when it stays quiet

  • Only someone who just wrote to the instance, one to one. Never a group, a channel, someone who wrote "STOP", the instance's own chat, one of WhatsApp's empty notices, or a message more than 15 minutes old.
  • A word or a digit opens it. A message with no words at all (an emoji, a sticker, a photo with no caption) does not open the menu, since that is what a reply to your status usually is. Once the menu is open, such a message is something that is not a choice.
  • One answer per message. A keyword auto-reply that is exactly the message answers first; then a choice of the open menu; then any other keyword; then your away reply, outside your working hours, once a day; then the menu. While the menu is on, it greets people in place of the welcome reply.
  • Never in a loop. Someone who keeps writing something that is not a choice sees the same menu twice at most. The third time, the chat goes to your team instead, with your handover line.
  • After a handover, everything automatic is quiet in that chat: the menu, keyword replies and the AI agent. That ends with whichever comes first: a teammate answers the chat from the panel or the phone; the chat is marked done; you send that person a message through the API; or 24 hours pass with nobody answering.
  • Your team takes over: once a teammate answers a chat, the menu stays quiet there for 24 hours, as the AI agent does.
  • With the AI agent on too, the menu comes first. After it, a message that is not a choice goes to the AI agent, and a choice is the menu's. If the agent answers only when your team has not (no_reply), that message waits for its delay first. They never both answer one message. See The AI agent.
  • Limits: the menu's messages are auto-replies: at most 5 an hour and 20 a day to one person, and they count in your plan like any message. Past them nothing more is sent, but a choice that hands over still gives the chat to your team.

In a chat, your team sees which messages the menu sent and the choice each one answers.

The API

GET /v1/instances/{id}/menu
PUT /v1/instances/{id}/menu
{
  "enabled": true,
  "greeting": "Hello! Reply with 1, 2 or 3.",
  "digits": "western",
  "back_label": "Back",
  "handover_message": "Someone from our team will answer you here.",
  "choices": [
    {"label": "Prices", "outcome": "answer", "answer": "A croissant is EGP 25."},
    {"label": "Orders", "outcome": "menu", "greeting": "About an order:", "choices": [
      {"label": "Delivery times", "outcome": "answer", "answer": "We deliver within 2 hours."},
      {"label": "A problem with my order", "outcome": "person"}
    ]},
    {"label": "Talk to someone", "outcome": "person", "message": "Mona will answer you shortly."}
  ]
}

The menu is one document. GET returns it, and PUT replaces it whole: send every choice, in the order they are numbered. What GET returns is what PUT takes. PUT needs a full-access key. A menu that would not work is refused with a 422 that names the field, and nothing changes.

  • enabled: whether the menu answers. greeting: the line above the choices, up to 600 characters. digits: western (1 2 3) or arabic (١ ٢ ٣).
  • handover_message: what a person is told when the chat goes to your team, also when the menu hands over by itself. back_label: what 0 is called in a sub-menu; needed when a choice opens one.
  • choices: 1 to 9. Each has a label (up to 40 characters, with at least one letter: its digit is added for you) and an outcome:
    • answer, with answer (up to 1,000 characters) or saved_answer_id;
    • menu, with its own choices (1 to 9, each answer or person) and, if you like, a greeting to show above them in place of the label;
    • person, with, if you like, a message of its own, assign_to (a teammate's id) and chat_label_id (one of your inbox labels). Choose these two in the panel: GET then shows their ids.
  • Two choices of one menu may not have the same label. A label, or back_label, may not be a word people send to stop or restart your messages, such as "Stop" or "Start".