Skip to main content

Connector

Connector Module: User-Friendly Configuration Guide

Welcome to the Connector setup! This tool lets your bot connect to other systems—like websites or apps—to send or get information. Think of it as your bot’s messenger to the outside world. You’ll set it up in a pop-up window (called a "modal") that’s easy to use—no coding needed!

What Does the Connector Do?​

The Connector helps your bot:

  • Fetch info (like getting the weather).
  • Send info (like creating a task).
  • Update or delete things (like changing a note or removing a file).

You’ll fill out a few fields in the pop-up to tell it where to go, what to do, and how to handle the reply.

Step-by-Step Setup in the Pop-Up Window​

When you open the Connector tool, a pop-up titled "Connector" slides up from the bottom. Here’s how to use it:

1. Give Your Connector a Name​

  • Where: The "Name" text box at the top.
  • What It Does: This is a label to remind you what this Connector is for (e.g., “Weather Checker” or “Task Sender”).
  • How to Set It Up: Type a short, clear name. It’s required, so you can’t leave it blank!

Example: Type “Email Sender” if it’s for sending emails.

2. Set the Destination (Url)​

  • Where: The "Url" text box.
  • What It Does: This is the web address where your bot sends its message—like a link (e.g., https://api.tasks.com).
  • How to Set It Up: Paste the address from the service you’re connecting to. If it depends on user input (like a city), use a placeholder like {user_city} tied to an earlier step. This is required too!

Example: For a weather service, type https://api.weather.com/today.

3. Pick an Action (Method)​

  • Where: The "Method" dropdown.
  • What It Does: Tells the Connector what to do at the destination. Options are:
    • GET: Ask for info (e.g., “What’s the weather?”).
    • POST: Send new info (e.g., “Make a task”).
    • PUT: Update something (e.g., “Change a task’s title”).
    • PATCH: Make a small tweak (e.g., “Fix a task’s date”).
    • DELETE: Remove something (e.g., “Delete a task”).
  • How to Set It Up: Click the dropdown and pick the right action. The service you’re connecting to should tell you which one to use. This is required!

Example: Choose “POST” to create a new task.

4. Add Extra Details (Params)​

  • Where: The "Params" table (a grid with columns).
  • What It Does: These are extra notes to make your message clear. The table has:
    • Name: What the note is called (e.g., “password” or “city”).
    • Value: What the note says (e.g., “xyz123” or “London”).
    • Key: Where it goes—“Header” (special rules) or “Query Params” (added to the URL).
  • How to Set It Up:
    1. Click the “+” button (a plus sign) to add a row.
    2. In “Name,” type the detail’s name (e.g., “Authorization”).
    3. In “Value,” type the info (e.g., “your_api_key” or {user_input}).
    4. In “Key,” click the dropdown and pick “Header” or “Query Params.”
    5. To edit or delete, use the pencil or trash icons next to each row.

Example:

  • Row 1: Name = “Authorization”, Value = “xyz123”, Key = “Header”.
  • Row 2: Name = “city”, Value = “New York”, Key = “Query Params”.

5. Write the Message (BODY)​

  • Where: The "BODY" box (a formatted text area with curly braces {}).
  • What It Does: This is the main info your bot sends—like task details. It’s needed for “POST,” “PUT,” or “PATCH,” and it’s required (leave as {} if empty).
  • How to Set It Up:
    1. For “GET” or “DELETE,” leave it as {}.
    2. For other actions, type info in this format: 
      {
        "title": "New Task",
        "description": "Do this today"
      }
    3. Use placeholders (e.g., {task_title}) for user input or earlier steps.

Example: For a task:

{
  "summary": "Fix the bug",
  "description": "Urgent!"
}

Tip: It looks like a list with curly braces—ask your admin for a sample if the service needs a specific layout.

6. Handle the Reply (Javascript function body)​

  • Where: The "Javascript function body" box (a big text area with code-like text).
  • What It Does: Tells the bot what to do with the reply—like saving it or showing it. You don’t need to be a coder!
  • How to Set It Up:
    1. By default, it says: 
      //here we need to return a pure JavaScript object 
      return {};
      Replace return {}; with return data; to save the full reply.
    2. For something specific (like a task ID), try return {id};.
    3. Ask your admin for help if you need a fancier tweak.

Example: To save a task ID, type:

return {id};

7. Test and Save Your Connector​

  • Where: The buttons at the bottom: "Test," "Save," "Save and close," "Close."
  • What It Does: Lets you check and store your setup.
  • How to Set It Up:
    1. Test: Click “Test” to try it out. A small window pops up showing if it worked (e.g., “Success” or an error). You need to save first if you’ve made changes.
    2. Save: Click “Save” to keep your setup without closing the pop-up.
    3. Save and close: Click “Save and close” to save and exit.
    4. Close: Click “Close” to exit without saving (if you didn’t hit “Save” yet, changes won’t stick).

Tip: Test first! If the test pop-up shows a green “Success” (like “200” or “201”), you’re good to save.

Special Tricks Made Easy​

Keeping It Safe (Encryption)​

  • What It Does: Scrambles your message so only the destination can read it.
  • How to Set It Up: In the "Params" table:
    1. Add a row: Name = “isEncrypted”, Value = “true”, Key = “Header”.
    2. Add another: Name = “key”, Value = “your_secret_word” (e.g., “mykey123”), Key = “Header”.

Example:

  • Row 1: Name = “isEncrypted”, Value = “true”, Key = “Header”.
  • Row 2: Name = “key”, Value = “task123”, Key = “Header”.

Connecting to Jira (Task Tool)​

  • What It Does: Simplifies talking to Jira, a task manager.
  • How to Set It Up: In the "Params" table:
    1. Add: Name = “isJira”, Value = “true”, Key = “Query Params”.
    2. Add more rows like:
      • Name = “project”, Value = “12345”, Key = “Query Params”.
      • Name = “summary”, Value = “New Task”, Key = “Query Params”.

Example:

  • Row 1: Name = “isJira”, Value = “true”, Key = “Query Params”.
  • Row 2: Name = “summary”, Value = “Fix this”, Key = “Query Params”.

Searching with Words​

  • What It Does: Splits a phrase into words for searching (e.g., “fix bug” becomes “fix” and “bug”).
  • How to Set It Up: In the "Params" table:
    • Add: Name = “phrase”, Value = “your words here”, Key = “Query Params”.

Example: Name = “phrase”, Value = “rain forecast”, Key = “Query Params”.

What Happens When It Runs?​

  1. The bot sends your message to the Url with the Method you picked.
  2. It waits for a reply (like “Task created!” or “Here’s the weather”).
  3. The "Javascript function body" decides what to save from the reply.
  4. If it works (e.g., “200” or “201” in the Test window), the bot moves to the next step. If not, you’ll see an error.

Troubleshooting Tips​

  • Can’t Save? Fill out Name, Url, Method, and BODY—they’re required (BODY can be {}).
  • Test Fails? Check the Url is correct and the service is online. Save changes first if you edited anything.
  • Weird Reply? Make sure Params and BODY match what the service expects—ask your admin for help.

That’s it! You’ve set up a Connector to link your bot to other tools. Fill out the pop-up, test it, and save it to see your bot in action. If you’re stuck, your admin is just a shout away!