Quickstart

​

Step 1: Sign Up and Get Your API Key

1. Go to the Copilotz landing page.
2. Click the Getting Started button at the top of the page. This will guide you through the account creation process.
3. After signing up, you’ll receive an access token (API key), which you’ll need to authenticate your API calls.
4. Your Copilotz account will automatically have access to the free sandbox environment, where you can test your integrations using a default WhatsApp number provided by Copilotz (extId: ABC123).

Note: If you’re on the free tier, you can use the provided WhatsApp sandbox number for testing. To link your own WhatsApp number for production, you will need to subscribe to a paid plan.

​

Step 2: Set Up WhatsApp Integration

​

Free Tier (Testing with Copilotz WhatsApp Number)

1. Upon completing the “Getting Started” process, a channel resource is automatically created. This channel links a WhatsApp hook to the Copilotz testing number (extId: ABC123).
2. Use the channels resource to manage this test channel and set up the allowList property to control which users can send messages to this number.

const updateChannel = async (accessToken) => {
  const channelId = 'your_channel_id';  // Channel ID created during the signup process
  const response = await fetch(`https://copilotz.com/rest/channels/${channelId}`, {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      allowList: ["5511987654321", "5511998765432"],  // List of phone numbers allowed to test the WhatsApp integration
    }),
  });

  if (response.ok) {
    console.log("Channel allowList updated successfully.");
  } else {
    console.error("Failed to update channel allowList.");
  }
};

​

Paid Plan (Connecting Your Own WhatsApp Number)

1. Click the “Connect WhatsApp” button on the landing page or within the dashboard.
2. This will guide you through the process of registering your WhatsApp number.
3. During this process, another channel resource will be created, linking your registered WhatsApp number to a WhatsApp hook and callback in Copilotz.
4. After setup, your WhatsApp number is ready to receive messages through Copilotz agents.

const getChannels = async (accessToken) => {
  const response = await fetch("https://copilotz.com/rest/channels", {
    method: "GET",
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });

  const channels = await response.json();
  console.log("Your Channels:", channels);
};

​

Step 3: Create Your First Copilotz Agent

1. Use the Copilotz resource to create a new agent. This agent will interact with users over WhatsApp, responding to messages and performing actions.

const createAgent = async (accessToken) => {
  const response = await fetch("https://copilotz.com/rest/copilotz", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      name: "My First Agent",
      description: "This agent will handle basic chat functionality.",
      backstory: "An AI agent to help users with common queries.",
      actions: [1, 2],  // IDs of actions this agent can perform
      job: 1,  // Job associated with this agent (e.g., Chatbot, Transcriber)
    }),
  });

  const agent = await response.json();
  console.log("Agent created:", agent);
};

​

Key Agent Types:

• Transcriber: Transcribes audio messages into text.
• Chat: Maintains conversation context, useful for chatbots.
• Function Call: Executes API requests or custom functions.
• Task Manager: Manages workflows with multiple steps and tasks.

Note: You can configure workflows for Task Manager agents, allowing them to follow specific steps to complete tasks. More details can be found in the Workflows section.

​

Step 4: Create an Action

const createAction = async (accessToken) => {
  const response = await fetch("https://copilotz.com/rest/actions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      name: "Send Welcome Message",
      description: "An action that sends a welcome message to the user.",
      specType: "native:request",  // Use native 'request' module to handle API requests
      moduleUrl: "native:request",  // Native handler for API requests
      spec: "...",  // OpenAPI or custom module specs
    }),
  });

  const action = await response.json();
  console.log("Action created:", action);
};

​

Step 5: Test in Sandbox Environment

1. Use the allowList to add your phone number to the test channel.
2. Send a WhatsApp message to the test number.
3. Your Copilotz agent will process the message and respond based on the actions you’ve configured.

​

Step 6: Move to Production

​

Next Steps

• Workflows: Learn how to define and manage multi-step workflows for your agents.
• Tasks: Understand how tasks are managed and progressed through workflows.
• Actions: Explore how to create custom actions and integrate with external APIs using OpenAPI specs.