How to Create an Outbound Email Task (Agent-Initiated) With the Interactions API in Node.js – Twilio Support

Objective

This article explains how to create an agent-initiated outbound email task using the Twilio Interactions API with a Node.js application. The example uses the Twilio Node Helper Library to initiate an email interaction that generates an outbound TaskRouter task and routes it according to your Flex configuration.

Product

Twilio Flex

Procedure

Use the Twilio Node Helper Library to send requests to the Interactions API.

The following example shows how to create an outbound email interaction initiated by an agent. Replace placeholder SIDs, email addresses, and credentials with values from your Twilio project.

const twilio = require("twilio");

const accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
const authToken = "your_auth_token";

const client = twilio(accountSid, authToken);

async function createInteraction() {
  const interaction = await client.flexApi.v1.interaction.create({
    channel: {
      type: "email",
      initiated_by: "agent", // Outbound task initiated by agent action

      // Required for email when initiated_by = agent
      properties: {
        from: "support@example.com",
        from_name: "Support Team",
      },

      // Required for agent-initiated interactions
      participants: [
        {
          level: "to",   // to | cc | bcc
          name: "John Doe",
          address: "customer@example.com",
        },
      ],
    },

    routing: {
      properties: {
        workspace_sid: "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        workflow_sid: "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        queue_sid: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",   // required for agent-initiated
        worker_sid: "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",  // required for agent-initiated

        task_channel_unique_name: "email",

        attributes: {
          customerName: "John Doe",
          customerEmail: "customer@example.com",
          interactionType: "agent-outbound-email",
        },
      },
    },
  });

  console.log("Outbound Email Interaction created!");
  console.log("Interaction SID:", interaction.sid);
}

createInteraction();

initiated_by: "agent" creates an outbound task assigned to the agent who initiated the interaction.
For email interactions initiated by an agent or API, from and from_name are required channel properties.
Participants are mandatory for agent-initiated interactions.
For routing, both queue_sid and worker_sid must be provided for agent-initiated tasks.
All routing attributes are forwarded directly to TaskRouter and affect how the task is created and processed.

Additional Information