Composio connector — flowwork docs

Composio connectors let a workflow act on a user’s third-party accounts — send a Gmail message, create a Calendar event, append to a Sheet — without your workflow ever handling the user’s credentials. Auth is per end-user and OAuth-based, connected through the web console.

Connect an account (one-time, in the console)

Open the console at http://localhost:9010 → Connections → Connected Accounts.
Connect the account (e.g. Gmail) via its OAuth flow.

Connecting both authenticates the account and auto-creates a ready-to-use connector instance you reference from a connector() step. Connection names look like composio_gmail, composio_googlecalendar, etc.

Engine configuration

The OAuth flow is UI-driven and needs COMPOSIO_API_KEY and COMPOSIO_AUTH_CONFIGS configured on the engine. flowctl only manages the resulting instances — the connect step happens in the console.

The envelope (this trips people up)

Composio’s adapter does not wrap arguments the way HTTP does:

requestMapper(ctx) returns the action’s flat arguments — e.g. { recipient_email, subject, body } — not nested under body/arguments.
responseCombiner(ctx, response) receives { data, successful, error }. Read results from response.data.X and check response.successful.

function build_email(ctx) {
  return { recipient_email: ctx.vars.to, subject: ctx.vars.subject, body: ctx.vars.body };
}
function read_result(ctx, response) {
  var data = response.data || {};
  return {
    sent: response.successful === true,
    message_id: data.id || data.message_id || "",
    send_error: response.error || null,
  };
}

connector("send_email", {
  connection: "composio_gmail",
  operation: "send_email",       // maps to the GMAIL_SEND_EMAIL action
  instance: "my-gmail",          // the instance created when the user connected Gmail
  requestMapper: build_email,
  responseCombiner: read_result,
  onError: "send_error_step",
  next: "finish",
});

Confirm the exact arg names

Action argument names vary by action. Before writing the mapper, run flowctl conn schema composio_gmail send_email to see the exact request_schema / response_schema and match them.

See the connector model in the overview, and the runnable examples/workflows/composio-gmail.js.