How-to guide

Send a call's details to your CRM

When a call ends, send what the agent captured to your own CRM through an HTTP tool you approved, with no server of your own.

What you'll build

A rule that runs when a call captures details: it sends the name, email and phone number the agent collected to your CRM, once per call. This guide uses Twenty and its REST API to create a Person. The same steps work for any CRM or system with a web address you can call.

You don't host anything. The rule uses an action that an Admin of your workspace has already approved, and every run is on record: on the call's timeline, in the rule's log, and as an action.completed or action.failed webhook.

How it works

  1. Your agent captures details during the call (name, email, and so on).
  2. The call ends, and the worker reports what it captured.
  3. The rule runs your HTTP tool once, with the values you mapped, read from the call at that moment.
  4. The outcome appears in the rule's log, and Run again is there if it failed.

The caller's words are sent exactly as they said them, so they are not verified. Only the tool you pick gets them, and only because you switched on "send real caller details" for it.

Prerequisites

  • A workspace Admin. Adding a rule that sends a caller's details somewhere is an Admin's decision.
  • An agent that captures at least a name, and optionally an email. Declare the details in the agent and publish it. See Forms for how an agent collects details.
  • A Twenty workspace, its API address (for example https://api.twenty.com, or your own server) and an API key.

Step 1: Create the HTTP tool

In the dashboard open Tools and choose New HTTP tool.

  1. Name: create_lead. Method: POST.

  2. URL template: https://api.twenty.com/rest/people. Use your own address if you host Twenty.

  3. Allowed hosts: api.twenty.com. A tool can reach only the sites you list.

  4. Sign in with: choose Create a connection and save your Twenty API key as a bearer token. The key stays in your workspace's vault and is attached when the tool runs. Never put it in a header or in the body.

  5. Inputs:

    [
      { "name": "firstName", "type": "string", "required": true },
      { "name": "email", "type": "string", "required": false },
      { "name": "phone", "type": "string", "required": false }
    ]
  6. Body template: the names and nesting are Twenty's. Check them against your Twenty's API reference, because they change between versions.

    {
      "name": { "firstName": "{{firstName}}" },
      "emails": { "primaryEmail": "{{email}}" },
      "phones": { "primaryPhoneNumber": "{{phone}}" }
    }
  7. Switch on Send real caller details (not masked tokens). A rule runs after the call, when there is no one to mask anything for, and it is refused (naming this switch) if the tool would send placeholders.

Choose Create tool.

Step 2: Approve the tool

A tool runs only after an Admin approves it. Open Tools, go to the approvals tab and approve create_lead. If you edit the tool later, it is paused for every agent until an Admin approves the change.

Step 3: Give the tool to the agent

Open the agent, then its Actions card.

  1. Add create_lead.
  2. Turn on Send the person's real details.
  3. Leave Ask the person first off. After a call nobody is on the line to say yes, so a rule cannot run a tool that asks first: it is refused with needs_person, and the form tells you before you save.
  4. Publish the agent. The version seals the tool, and the rule runs against the version that took the call.

Step 4: Add the rule

Open Settings, then Notifications, and choose Run an action. You can also add it from the agent's own Notifications card.

  1. When a call captures details on: your agent. A rule works on one agent.

  2. Run: create_lead.

  3. Send these to it: map each input of the tool. The form fills in what it can match by name.

    InputComes from
    firstNameWhat the caller said: name
    emailWhat the caller said: email
    phoneThe caller's phone number

    Each input takes one of three things: a detail the agent captured, a fact about the call (its id, how long it lasted in seconds or milliseconds, how it ended, whether it was inbound, outbound or on the web, the caller's phone number), or a value you type once. A model never fills them.

  4. Also on test calls: on by default. Leave it on for now.

  5. At most this many runs an hour: leave it empty unless your CRM has a rate limit. Runs over a limit you set wait for a free hour; none are dropped.

  6. Choose Add rule.

The phone number is the caller's number only when it is a real phone number. On a web call the caller has no number, so an input that needs one finishes as "a detail the action needs was empty" and nothing is sent. An optional input is left out.

Test it

Open the Playground, start a call with your agent, give it a name and an email, and end the call. A Playground call is a test call: the rule runs your tool for real, and the log marks it "test call".

Open Settings, then Notifications, then What happened lately under your rule. You should see Ran the action. Open the Person in Twenty to confirm.

When you are happy, you can switch Also on test calls off so only real calls reach your CRM.

Read the log

What the log saysWhat it meansWhat to do
Ran the actionYour tool answered with success.Nothing.
The action failedYour tool ran and the CRM refused or errored.Fix the cause, then Run again.
Sent, but we could not confirm it workedThe request left, and no answer came back in time.Check the CRM before you Run again: it may have been created.
Not run: refusedThe tool was not allowed to run. The reason follows, for example it asks the person first, real details are off, or it is not approved.Fix what the reason says; Run again.
Not run: a detail the action needs was emptyThe call did not capture a value a required input needs.Make the agent ask for it, or map the input to another source.
Not run: the details no longer fit the actionThe agent or the tool changed since you saved the rule.Add the rule again.
Will try againSomething that clears by itself, or an Admin's approval, is holding it.Nothing, or approve the tool.

Run again is for Admins, because it sends the caller's details again. It is one more run under its own key, and two people pressing it at once make one run.

Limits

This is what works today, and what does not yet. The numbers are in the team's list of known gaps, docs/architecture-notes/sales-demo-dogfood-follow-ups.md.

  • Twenty is not a built-in connector (DF-82). You write the HTTP tool yourself, as above.
  • Every value is sent as text, and a missing one as an empty string (DF-83). A number arrives as "25". An optional input the call did not fill is sent as "", which some CRMs reject for an email. Make the agent require the details your CRM insists on.
  • Inputs are text, numbers or yes/no (DF-84). A list the agent captured (several interests) is joined into one text with commas.
  • The tool's answer cannot be used (DF-85). You can't create a Person and then use its id in a second step.
  • No OpenAPI import (DF-86). You type the tool's inputs and body by hand.
  • Only calls (DF-87). A text conversation has no "ended" event yet, so a rule cannot run when a chat or a text thread ends.
  • Only your own HTTP and MCP tools. Built-in actions, a connected app such as HubSpot, and a hosted channel's actions cannot be run from a rule yet.
  • The transcript is not a source. A rule sends captured details and call facts, not the conversation.
  • The tool must send real details and must not ask first. Both are your choices on the tool and the grant; the platform only refuses what you set.

The rest of that list (DF-88 to DF-90) is about the builder and the internal CRM and doesn't affect this flow.

Common errors

ErrorStatusHow to fix
not_found404Check the id, and that the key belongs to the workspace (and covers the channel) that owns it.
insufficient_scope403Use a key with the scope named in details.required, or one whose restriction covers this channel or Binding.

On this page