Retell AI API Integration: Automate Calls and CRM Workflows

A gross sales dialog turns into extra helpful when its end result reaches the precise enterprise system. Retell AI supplies APIs for constructing voice brokers, managing calls, and retrieving dialog information that different functions can use.

Listed in G2’s AI Voice Agent Platform Software program class, Retell helps voice automation throughout gross sales, customer support, and enterprise operations.

This text explains its integration strategies, examines G2 reviewer experiences, and demonstrates a Retell-to-HubSpot workflow with Node.js code examples.

One G2 reviewer describes Retell’s API as straightforward to combine and well-documented for builders. One other reviewer highlights the convenience of incorporating Retell into an current product.

A extra detailed instance comes from a reviewer constructing buyer assist brokers, who describes utilizing customized instruments to question databases, create assist tickets, and set off workflows throughout reside conversations. This illustrates how an agent can work together with enterprise techniques as a substitute of relying fully on info contained in its preliminary directions.

Put up-call automation is one other use case. A reviewer deploying outbound voice brokers describes extracting reserving standing, objections, and different structured outcomes and passing them to a CRM via webhooks.

These experiences assist distinguish two frequent necessities: accessing info whereas a dialog is going on and processing its end result afterward.

The place do customers see alternatives for enchancment?

Some reviewers counsel increasing the superior implementation steerage and simplifying the connections to particular functions.

A G2 reviewer describes experimenting with post-call webhooks and customized evaluation schemas, whereas suggesting extra detailed troubleshooting info for unsuccessful calls.

One other reviewer particularly suggests extra intensive documentation for software calling.

Native connectivity is one other space reviewers have mentioned. A reviewer utilizing Retell for gross sales automation valued customized capabilities and webhooks however needed a extra direct GoHighLevel integration. Retell now paperwork a native GoHighLevel connection, so this suggestions describes the reviewer’s expertise on the time fairly than a confirmed present integration hole.

These ideas mirror particular person experiences throughout the analysis interval, not limitations essentially affecting each Retell consumer or remaining unresolved within the present product.

Register to the Retell AI dashboard and create a voice agent.

For a lead qualification workflow, configure it to gather related info, such because the prospect’s necessities and curiosity in a follow-up.

Within the agent editor, open Put up Name Extraction and configure customized Boolean fields akin to:

• lead_qualified: Signifies whether or not the prospect meets the qualification standards.
• followup_needed: Signifies whether or not extra contact is required.

These fields are examples that you have to configure your self. The mixing beneath makes use of lead_qualified; extra fields akin to followup_needed require their very own CRM mapping.

Check the agent’s dialog habits and assign a appropriate outbound telephone quantity to the supposed agent.

Confer with Retell’s agent configuration documentation and Put up Name Extraction documentation.

Step 2: Generate API credentials

Create a Retell API key within the dashboard for initiating calls. Determine the Retell API key marked with the webhook verification badge. Retell designates this key for verifying webhook signatures.

For this practice server-to-server HubSpot integration, create a Service Key below Settings > Integrations > Service Keys and grant the crm.objects.contacts.write scope. You want acceptable Developer Instruments entry and permissions to create a Service Key. Service Keys present scoped API entry with out requiring a brand new legacy personal app.

HubSpot disabled creation of recent legacy personal apps for current accounts on October 26, 2026. Present legacy personal app credentials stay usable throughout their supported lifecycle. A legitimate OAuth entry token is an alternative choice when an software makes use of OAuth.

Necessary: HubSpot Service Keys don’t assist HubSpot’s personal app webhook options. That limitation doesn’t forestall this instance from receiving Retell webhooks on an independently hosted endpoint and utilizing a Service Key to replace HubSpot contacts.

You will additionally want a take a look at contact and two customized contact properties, that are described in Step 6.

Retailer the next credentials and configuration values in a .env file:

• RETELL_API_KEY: Your Retell API key.
• RETELL_WEBHOOK_API_KEY: The API key designated for webhook verification.
• RETELL_FROM_NUMBER: Your configured outbound telephone quantity.
• TEST_TO_NUMBER: Your licensed take a look at quantity.
• PORT: The native port utilized by the instance webhook server (akin to 3000).
• WEBHOOK_BODY_LIMIT: The utmost accepted Retell webhook physique dimension. For instance, add WEBHOOK_BODY_LIMIT=2mb to your .env file as an illustrative beginning worth; regulate it to anticipated payloads and implement an affordable higher certain.
• HUBSPOT_ACCESS_TOKEN: Your HubSpot Service Key or one other licensed bearer token.
• HUBSPOT_CONTACT_ID: The ID of your take a look at contact.

Use E.164 worldwide formatting for telephone numbers, akin to +14155550123.

Hold credentials in your backend and exclude .env from model management. The 2 Retell API key variables might include the identical worth in case your designated webhook key can be used to provoke calls.

The instance beneath doesn’t retry outbound name creation robotically. Retrying a request with no supported and appropriately configured idempotency mechanism might place a second name.

See Retell’s API key documentation and HubSpot’s Service Key steerage.

Step 3: Set up the Node.js SDK

Initialize a Node.js venture and set up Retell’s SDK, Categorical, and dotenv:

npm init -y
npm set up retell-sdk categorical dotenv

Configure the venture’s package deal.json with "kind": "module" to allow JavaScript module syntax.

Use a supported Node.js LTS launch, akin to Node.js 24 or 26. Each embody the built-in fetch() API for the HubSpot request.

Step 4: Provoke a name and determine the CRM contact

To provoke an outbound telephone name utilizing the Retell AI API, create a file named create-call.js and initialize Retell’s official SDK utilizing your API key:

import 'dotenv/config';
import Retell from 'retell-sdk';

const retell = new Retell({
  apiKey: course of.env.RETELL_API_KEY
});

const name = await retell.name.createPhoneCall({
  from_number: course of.env.RETELL_FROM_NUMBER,
  to_number: course of.env.TEST_TO_NUMBER,
  metadata: {
    hubspot_contact_id: course of.env.HUBSPOT_CONTACT_ID
  }
});

console.log('Retell name ID:', name.call_id);

Use the SDK’s name.createPhoneCall() technique to provoke an outbound name. The request ought to embody:

• from_number: The configured outbound telephone quantity.
• to_number: The licensed vacation spot quantity.
• metadata: An object containing hubspot_contact_id.

Earlier than putting a name, full Steps 5 and 6, begin the webhook listener with node server.js, expose its /webhook route via a public HTTPS endpoint, and register that URL in Retell. As soon as the listener is prepared, run node create-call.js. A profitable request returns a call_id.

Why embody the contact ID? It permits the backend to determine which CRM report ought to obtain the decision end result when the webhook arrives.

Retell metadata shops this identifier with the decision, however doesn’t robotically make CRM info out there to the voice agent throughout its dialog. If the agent wants contact particulars whereas talking, configure acceptable dynamic variables or external-data entry individually.

Retell’s Create Telephone Name API additionally paperwork an non-obligatory idempotency_key to assist forestall duplicate calls when retrying the identical request inside one hour. This minimal instance omits the sphere; verify assist in your put in SDK model earlier than including computerized retries.

Examine telephone quantity restrictions: Each numbers should use E.164 formatting. Retell’s Create Telephone Name API at present limits Retell-purchased telephone numbers to US locations. Different telephony configurations might have totally different restrictions.

Use solely licensed take a look at numbers. Actual calls might incur expenses and are topic to relevant calling, consent, and do-not-call necessities.

See Retell’s Create Telephone Name API reference.

Step 5: Obtain and confirm the analyzed name end result

To obtain name transcripts and post-call evaluation via Retell AI webhooks, configure a publicly accessible HTTPS endpoint and register its URL in Retell. Allow the call_analyzed occasion to obtain accomplished evaluation and out there transcript information. You may configure an account-level or agent-level webhook. When an agent-level webhook URL is configured, Retell makes use of it as a substitute of the account-level URL for that agent.

Why use call_analyzed? It’s triggered when post-call evaluation is full and consists of the call_analysis object. The sooner call_ended occasion doesn’t embody that object.

Earlier than processing an occasion, confirm its authenticity utilizing the unique request physique.

Retell supplies Retell.confirm() for checking the X-Retell-Signature header towards the uncooked request physique. Use the designated webhook verification API key. The next instance lives in server.js and imports the updateContact perform from Step 6:

import 'dotenv/config';
import categorical from 'categorical';
import Retell from 'retell-sdk';
import { updateContact } from './hubspot.js';

const app = categorical();
const processedEvents = new Set(); // Demo solely: not sturdy.

app.use('/webhook', categorical.uncooked());

app.publish('/webhook', async (req, res) => {
  if (!Buffer.isBuffer(req.physique)) {
    return res.sendStatus(415);
  }

  const rawBody = req.physique.toString('utf8');
  const signature = req.headers['x-retell-signature'];

  if (
    typeof signature !== 'string' ||
    !(await Retell.confirm(
      rawBody,
      course of.env.RETELL_WEBHOOK_API_KEY,
      signature
    ))
  ) {
    return res.sendStatus(401);
  }

  let payload;

  attempt {
    payload = JSON.parse(rawBody);
  } catch {
    return res.sendStatus(400);
  }

  if (!payload || typeof payload !== 'object') {
    return res.sendStatus(400);
  }

  const { occasion, name } = payload;

  if (occasion !== 'call_analyzed') {
    return res.sendStatus(204);
  }

  if (!name?.call_id) {
    return res.sendStatus(400);
  }

  const eventKey = `${occasion}:${name.call_id}`;

  if (processedEvents.has(eventKey)) {
    return res.sendStatus(204);
  }

  const contactId = name.metadata?.hubspot_contact_id;
  const abstract = name.call_analysis?.call_summary;
  const certified =
    name.call_analysis?.custom_analysis_data?.lead_qualified;

  // Conservative lead-qualification allowlist.
  // Transfers and different endings want separate evaluate.
  const allowedReasons = new Set([
    'agent_hangup',
    'user_hangup'
  ]);

  if (
    !contactId ||
    name.call_status !== 'ended' ||
    !allowedReasons.has(name.disconnection_reason) ||
    name.call_analysis?.in_voicemail !== false
  ) {
    return res.sendStatus(204);
  }

  if (
    (typeof abstract !== 'string' || !abstract.trim()) &&
    typeof certified !== 'boolean'
  ) {
    return res.sendStatus(204);
  }

  attempt {
    await updateContact(contactId, abstract, certified);
    processedEvents.add(eventKey);
    return res.sendStatus(204);
  } catch (error) {
    console.error('CRM replace failed:', error);
    return res.sendStatus(500); // Retell might retry.
  }
});

app.pay attention(
  Quantity(course of.env.PORT || 3000),
  () => console.log('Webhook server listening')
);

If verification fails, the webhook handler ought to return an HTTP 401 Unauthorized response.

Plan for outsized webhook occasions: Giant call_analyzed payloads might exceed the server’s request-body restrict and obtain HTTP 413 earlier than the handler runs. The WEBHOOK_BODY_LIMIT setting makes that restrict configurable; 2mb is an instance, not a assured most. Monitor precise payload sizes and align any reverse-proxy limits with out eradicating smart useful resource protections. If supply fails, examine the rejected occasion and reconcile the decision utilizing Retell’s Get Name API when its name ID is thought and the required information stays out there below your retention settings. Retrieving a name is a restoration step, not an computerized webhook replay.

Don’t confirm a re-serialized JSON object. Use the uncooked request physique as a result of modifications to formatting or key order can invalidate the signature. If utilizing Categorical, configure raw-body dealing with for the webhook route earlier than JSON physique parsing.

After profitable verification, the handler parses the JSON, filters for call_analyzed, checks for non-conversation outcomes, and extracts the CRM contact and evaluation fields. After creating hubspot.js in Step 6, begin server.js and register its public HTTPS endpoint in Retell earlier than working create-call.js.

For a call_analyzed occasion, retrieve:

• Contact ID: name.metadata.hubspot_contact_id
• Name abstract: name.call_analysis.call_summary
• Qualification outcome: name.call_analysis.custom_analysis_data.lead_qualified
• Occasion identifier: A mix of the occasion title and name.call_id

Earlier than updating HubSpot, verify the decision end result and ensure that the required info is offered.

Why verify the decision end result? Retell can ship call_analyzed even when an outbound name by no means connects. Outcomes akin to dial_failed, dial_no_answer, and dial_busy mustn’t robotically be categorized as unqualified leads.

This conservative instance accepts solely calls ending with agent_hangup or user_hangup, excludes voicemail, and checks for a contact ID plus a usable abstract or Boolean qualification outcome. Transfers, timeouts, and different endings are deliberately excluded till their dealing with has been examined.

Lacking voicemail evaluation additionally skips the replace: The situation in_voicemail !== false requires Retell to explicitly return in_voicemail: false. Calls the place Retell omits this subject are excluded even when the dialog in any other case accomplished efficiently. Check this conservative habits towards consultant calls earlier than utilizing it in manufacturing.

Adapt this conservative filter to the enterprise workflow and validate its impact on accomplished calls.

How dependable is AI-generated lead qualification? Put up-call qualification values are AI-generated assessments. Check the configured extraction standards towards consultant conversations earlier than utilizing them to set off automated gross sales actions.

Shield webhook information: Retell paperwork that transcripts and recordings might stay accessible via webhook supply even when post-call storage is disabled. Deal with webhook payloads as delicate; retain solely required information and apply entry and retention controls.

See Retell’s webhook overview and webhook safety documentation.

Step 6: Replace the HubSpot contact

The CRM replace ought to occur solely after webhook authentication and call-data validation. This instructional instance updates HubSpot straight from server.js; it doesn’t retailer an replace job. Manufacturing functions ought to persist occasions and use a devoted employee.

First, create two customized contact properties in HubSpot:

• retell_call_summary: A multi-line textual content property for the decision abstract.
• retell_lead_qualified: A single-checkbox property that shops Boolean values utilizing true and false.

These are instance inside property names. They don’t seem to be robotically created by Retell or HubSpot. Affirm that the properties exist and are writable earlier than working the combination.

Create hubspot.js with a perform that sends a PATCH request to the HubSpot 2026-09 Contacts endpoint. The property names are the customized fields described above:

export async perform updateContact(
  contactId,
  abstract,
  certified
) {
  const properties = {};

  if (typeof abstract === 'string' && abstract.trim()) {
    properties.retell_call_summary = abstract;
  }

  if (typeof certified === 'boolean') {
    properties.retell_lead_qualified = String(certified);
  }

  if (Object.keys(properties).size === 0) {
    return;
  }

  const url =
    `https://api.hubapi.com/crm/objects/2026-09/contacts/${encodeURIComponent(contactId)}`;

  const response = await fetch(url, {
    technique: 'PATCH',
    headers: {
      Authorization: `Bearer ${course of.env.HUBSPOT_ACCESS_TOKEN}`,
      'Content material-Kind': 'software/json'
    },
    physique: JSON.stringify({ properties })
  });

  if (!response.okay) {
    throw new Error(
      `HUBSPOT_UPDATE_FAILED (HTTP ${response.standing})`
    );
  }
}

Authenticate utilizing the HubSpot Service Key or one other licensed bearer token and submit the modified fields within the JSON properties object.

For the qualification property, convert the Boolean outcome into the string "true" or "false", as required by the instance single-checkbox configuration.

Necessary: The replace assumes the customized properties exist and settle for the equipped values. A distinct property kind or configuration might require a unique worth format.

Omit the abstract when it’s empty or lacking, and omit the qualification property when the outcome isn’t a Boolean. This helps forestall incomplete name evaluation from overwriting current CRM values.

HubSpot’s 2026-09 APIs implement relevant account-configured CRM write-validation guidelines. Invalid requests could also be rejected. Appropriate the submitted information earlier than retrying a validation failure as a substitute of repeatedly submitting the identical invalid request. The instance studies solely a managed error identifier and HTTP standing fairly than logging the total HubSpot response physique, which might include CRM-related particulars.

For implementation particulars, discuss with HubSpot’s CRM Objects API documentation, date-based API migration steerage, and CRM write-validation documentation.

Manufacturing consideration: The demonstration connects hubspot.js to server.js via an import and calls HubSpot throughout the webhook request. Its in-memory occasion monitoring doesn’t assure exactly-once processing or forestall simultaneous requests from updating the identical contact twice. Earlier than deployment, use sturdy occasion storage, atomic deduplication, and a separate processing employee. Don’t await a doubtlessly gradual HubSpot request earlier than acknowledging a safely continued webhook occasion.

The supposed workflow is:

HubSpot contact → Retell telephone name → Put up-call evaluation → Verified webhook → HubSpot contact replace

Step 7: Check the entire workflow

Earlier than deployment, use licensed telephone numbers and take a look at CRM information to confirm the workflow.

Examine that:

• The supposed voice agent handles the decision.
• The outbound telephone quantity helps the chosen vacation spot.
• The decision metadata comprises the right HubSpot contact ID.
• Outbound name requests aren’t robotically retried, and repeated execution is examined rigorously to keep away from duplicate calls.
• Retell delivers call_analyzed with the configured evaluation fields.
• The webhook signature is verified utilizing the designated API key and unique request physique.
• Invalid webhook signatures obtain an HTTP 401 response.
• Solely allowlisted name endings are eligible for qualification updates; failed, unanswered, voicemail, and unreviewed name endings are excluded.
• The webhook handler invokes the HubSpot replace perform efficiently.
• The proper HubSpot contact receives the anticipated abstract and qualification values.
• Duplicate deliveries are examined, noting that in-memory deduplication doesn’t forestall concurrent or post-restart duplicate updates.
• Lacking evaluation values are skipped; HubSpot errors return a failure response, and manufacturing retry habits is examined individually.

Earlier than manufacturing deployment, change the demonstration’s in-memory deduplication with persistent occasion storage and a separate processing employee, then take a look at the entire workflow.

Sure. Retell can join with automation platforms via supported integrations, APIs, and webhooks. A G2 reviewer particularly describes integration with n8n and Make.com for advanced automation workflows. The out there setup is dependent upon the platform and the actions you wish to automate.

This autumn. Can Retell AI automate voice, SMS, and chat conversations?

Retell helps voice brokers, chat capabilities, and documented SMS performance. Nonetheless, the out there API operations and setup necessities differ by channel. Companies planning multichannel automation ought to confirm supported capabilities and occasions for every workflow.

Q5. Can builders select the language mannequin utilized by Retell AI?

Retell supplies language-model configuration choices and helps customized LLM approaches for relevant agent setups. The out there decisions rely on the agent kind and response engine, so builders ought to confirm mannequin compatibility for his or her particular configuration.

Q6. When must you use a local Retell AI CRM integration as a substitute of a customized API integration?

Use a local integration when it helps the required CRM, information fields, and workflow. Select a customized integration while you want extra management over name initiation, report mapping, occasion processing, or actions that the native connector doesn’t assist.

Q7. Is Retell AI API integration free?

Retell AI consists of API and webhook entry in its pay-as-you-go providing, however utilizing voice brokers isn’t essentially free. Fees rely on utilization, chosen fashions, telephony, and different relevant companies. Examine Retell AI’s present pricing earlier than deployment.

How will you get extra worth from Retell AI integrations?

Retell AI API integration helps companies transfer past automated conversations by connecting voice brokers with the techniques that assist gross sales, customer support, and every day operations. Whether or not you are updating CRM information, scheduling appointments, or triggering follow-ups, the precise integration is dependent upon the info your brokers want and the actions you wish to automate.

Begin with a clearly outlined workflow, select between native connectors and customized APIs, and validate the entire course of earlier than deployment.

Exploring different AI-powered voice instruments? Learn G2’s finest AI voice assistants listicle to match capabilities and actual consumer experiences.