.png)
Retell AI Integration Guide
Connect Retell AI voice agents with enterprise applications through REST APIs, selected webhook events, and Martini workflows.
Retell AI integration options at a glance
Retell AI provides REST APIs for managing Agents, Calls, Phone Numbers, Knowledge Bases, Voices, and call-related operations, including outbound and web calls. Selected call lifecycle and post-call events can be delivered through webhook notifications. Calls are asynchronous, so integrations should store the Retell call identifier and retrieve final details or analysis after processing completes. Knowledge-base content can be uploaded or referenced through the relevant APIs, although this is not a general-purpose file API. Martini can consume these APIs, receive and validate webhook requests, map voice data to enterprise systems, expose internal APIs, and use scheduled or controlled workflows for reconciliation.
| Integration point | Supported by Retell AI? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Manage Agents, Calls, Phone Numbers, Knowledge Bases, and related resources; initiate outbound or web calls and retrieve call details and analysis. | Martini can consume the Retell AI REST API from workflows, transform payloads, apply business rules, and expose internal APIs that abstract Retell AI operations. |
| Webhooks and outbound callbacks | Yes | Receive selected call lifecycle and post-call notifications, such as call started, call ended, and call analyzed events. | Martini can expose an HTTP workflow or API endpoint, validate the webhook signature, apply idempotency checks, and route events to enterprise systems. |
| Bulk, asynchronous, and batch processing | Limited | Calls continue asynchronously after the initiating request returns. A broad bulk API for all Retell AI resources was not confirmed. | Martini can store call IDs, use webhook completion signals, and implement controlled iteration, queues, or scheduled polling subject to account limits. |
| Knowledge-base content APIs | Limited | Upload or reference source content used by Retell AI Knowledge Bases. Supported formats, limits, and processing behavior should be verified for the intended implementation. | Martini can retrieve source content, transform supported metadata and content fields, invoke knowledge-base operations, and record synchronization results. |
| Authentication | Yes | Retell AI REST requests use an API key as a bearer token in the Authorization header. Webhook signatures should be validated independently. | Martini can keep API keys and webhook verification secrets in protected environment configuration or Secrets Management and apply them to outbound and inbound flows. |
| GraphQL APIs | Not confirmed | No official Retell AI GraphQL API was identified in the supplied research. | Martini should use the documented REST APIs rather than assume GraphQL support. |
| SOAP APIs | No | Retell AI integration documentation is REST- and webhook-oriented; SOAP support was not confirmed. | Martini can consume SOAP services generally, but a Retell AI SOAP integration should not be assumed. |
| Database and analytics access | Not confirmed | No direct Retell AI database or general-purpose analytics database interface was confirmed. | Martini can retrieve call information through the API or webhooks and persist it in a downstream database when required. |
How Retell AI exposes data and business events
Retell AI REST APIs
Retell AI exposes REST endpoints for Agents, Calls, Phone Numbers, Knowledge Bases, and related operations. The APIs can initiate calls and retrieve current call details or analysis.
Martini implementation pattern
Martini implementation pattern: Martini workflows authenticate with a protected bearer API key, call the required Retell AI endpoint, validate responses, transform payloads, and expose controlled Martini APIs when internal applications should not call Retell AI directly.
Implementation sequence
Retell AI Webhooks
Retell AI supports webhook-style notifications for selected call and related events, including call started, call ended, and call analyzed notifications. Coverage is event-specific rather than universal for every resource operation.
Martini implementation pattern
Martini implementation pattern: Martini exposes an HTTP endpoint, validates the Retell AI webhook signature, acknowledges valid events quickly, and delegates longer retrieval and downstream processing to a workflow that uses the call ID for idempotency.
Implementation sequence
Asynchronous Call Processing
Retell AI call execution continues after an initiating API request returns. Final transcripts, recordings, and Call Analysis may only become available after the call or analysis has completed.
Martini implementation pattern
Martini implementation pattern: Martini records the returned Call identifier immediately, uses suitable webhook events as the completion signal, and falls back to controlled polling or scheduled reconciliation when an event does not provide the required data.
Implementation sequence
Knowledge Base Content
Retell AI provides Knowledge Base operations for uploaded or referenced source content. Exact formats, limits, and processing behavior should be verified against the current vendor documentation.
Martini implementation pattern
Martini implementation pattern: A scheduled workflow or source event detects content changes, retrieves the source document, maps supported fields to Retell AI Knowledge Base operations, and records success or failure for retry and reconciliation.
Implementation sequence
Common Retell AI integration patterns
Pattern 1: Sync completed calls to a CRM
When to use this pattern
Use this pattern when sales or support teams need completed Retell AI calls, transcripts, summaries, and analysis in Salesforce, HubSpot, or another CRM. Webhook delivery provides the trigger, while the REST API supplies authoritative details when the event payload is incomplete.
Integration direction
Example Mapping
| Retell AI Field | Canonical Field | Target Field |
|---|---|---|
| call_id | externalCallId | Retell_Call_ID__c |
| call_status | callStatus | Status |
| transcript | conversationTranscript | Description |
| call_analysis.summary | callSummary | Summary__c |
Martini implementation pattern
Martini receives and validates the event, checks the Call identifier against an event-processing store, retrieves the latest Call and Call Analysis data, normalizes timestamps and status values, and writes or updates the CRM activity. Retryable API failures are retried without creating a duplicate because the Retell call ID is the durable external key.
Martini capabilities used
- workflows
- API consumption
- webhook handling
- data mapping
- business rules
- error handling
Pattern 2: Initiate outbound calls from a CRM
When to use this pattern
Use this pattern when an approved CRM process or internal application needs to initiate a Retell AI outbound call and later receive the result. The initiating response should return the Call identifier without treating it as a completed conversation.
Integration direction
Example Mapping
| Retell AI Field | Canonical Field | Target Field |
|---|---|---|
| contact.phone | customerPhoneNumber | to_number |
| agent_id | approvedAgentId | agent_id |
| campaign_id | campaignReference | metadata.campaign_id |
| phone_number_id | callerNumberId | from_number |
Martini implementation pattern
Martini exposes a controlled API, validates the customer number and environment-specific Agent and Phone Number identifiers, maps the request to the Retell AI outbound-call API, and returns the Call ID. Later webhook events are correlated to the CRM request and update the activity or disposition after completion.
Martini capabilities used
- API exposure
- API consumption
- data mapping
- validation
- business rules
- asynchronous workflows
Pattern 3: Route call escalations to support
When to use this pattern
Use this pattern when Call Analysis, intent, extracted fields, or other post-call indicators determine whether a conversation requires human follow-up in Zendesk or ServiceNow.
Integration direction
Example Mapping
| Retell AI Field | Canonical Field | Target Field |
|---|---|---|
| call_analysis.intent | supportIntent | Category |
| call_analysis.summary | escalationSummary | Description |
| call_id | externalCallId | Correlation ID |
| phone_number | customerContact | Caller |
Martini implementation pattern
Martini validates the webhook, retrieves final call details, evaluates escalation and severity rules, and creates or updates the target ticket only when criteria are met. It records the source Call ID and routes failed writes to retry handling or an operational exception queue.
Martini capabilities used
- webhook handling
- workflow orchestration
- data mapping
- business rules
- error handling
- monitoring
Pattern 4: Synchronize enterprise knowledge to agents
When to use this pattern
Use this pattern when content maintained in Confluence, SharePoint, or another repository must be reflected in Retell AI Knowledge Bases. The design depends on the current supported ingestion formats and knowledge-base API behavior.
Integration direction
Example Mapping
| Retell AI Field | Canonical Field | Target Field |
|---|---|---|
| page.id | sourceContentId | external_source_id |
| page.title | contentTitle | title |
| page.body | contentBody | content |
| page.version | sourceVersion | source_version |
Martini implementation pattern
A Martini scheduled workflow or source event retrieves changed content, validates supported formats, maps source metadata and body content, and calls the Retell AI Knowledge Base API. The workflow stores source versions and processing outcomes so failed items can be retried without duplicating content.
Martini capabilities used
- scheduled workflows
- API consumption
- data mapping
- validation
- persistence
- error handling
Applications commonly integrated with Retell AI
Retell AI call data and agent operations can be orchestrated with named enterprise applications using REST APIs, webhooks, and Martini workflows. These are integration architecture patterns rather than claims of native Retell AI integrations.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Store call outcomes, transcripts, summaries, lead qualification results, and follow-up tasks in CRM records, while allowing approved Salesforce processes to initiate outbound calls. | Salesforce → Martini → Retell AI | Expose a Martini API for outbound-call requests, map Salesforce customer and campaign data to the Retell AI call request, then process call-ended or call-analyzed events back into Salesforce Activities and related records with the Retell call ID as the external key. |
| HubSpot | Associate Retell AI calls and generated summaries with Contacts, Companies, Deals, or Tickets. | Retell AI → Martini → HubSpot | Receive a selected Retell AI webhook event, retrieve complete call details when necessary, transform transcripts and analysis into HubSpot engagement properties, and apply duplicate checks before writing the result. |
| Zendesk | Create or update support tickets when a call indicates a customer issue or requires human escalation. | Retell AI → Martini → Zendesk | Route completed-call events through a Martini workflow, evaluate intent or call analysis, and create or update a Zendesk ticket containing the customer identifier, summary, escalation reason, and Retell call reference. |
| ServiceNow | Create incidents, cases, or tasks from support-call outcomes and route escalations to service teams. | Retell AI → Martini → ServiceNow | Validate the Retell webhook, apply escalation rules, map call analysis into the ServiceNow data model, and persist the Retell call ID to prevent duplicate incidents or tasks. |
| Twilio | Coordinate telephony configuration or calling services where Twilio numbers or services are used alongside Retell AI. | Twilio → Martini → Retell AI | Use Martini to coordinate approved phone-number and agent configuration, validate environment-specific identifiers, and call the relevant Retell AI REST operation after compatibility and account requirements are confirmed. |
| Slack | Notify sales, support, or operations teams about urgent call outcomes and escalations. | Retell AI → Martini → Slack | Use a post-call workflow to evaluate analysis or disposition fields, format a concise notification, and route only qualifying events to Slack while retaining the source call ID for traceability. |
| Microsoft Teams | Deliver operational notifications or escalation messages to contact-center and support teams. | Retell AI → Martini → Microsoft Teams | Transform selected Retell AI call events into Teams notifications through a Martini workflow, applying routing rules for team, severity, and customer context. |
| Confluence | Synchronize approved knowledge content into Retell AI Knowledge Bases so voice agents can use current enterprise information. | Confluence → Martini → Retell AI | Detect source changes through a scheduled workflow or source event, retrieve the content, map metadata and supported content fields to Retell AI Knowledge Base operations, and record synchronization status for reconciliation. |
How to build a Retell AI integration in Martini
Objective
Establish protected access to Retell AI and the Martini endpoint that will receive events.
Instructions in Martini
- Store the Retell AI API key in Martini Secrets Management or protected environment configuration.
- Store the webhook verification secret separately from the API key.
- Use separate development and production credentials where projects or environments are separated.
- Keep credentials out of browser applications, workflow payloads, and source-controlled mappings.
Objective
Select the event, API request, or schedule that starts the integration flow.
Instructions in Martini
- Use a Martini HTTP workflow or API for Retell AI webhook events.
- Use an internal Martini API for CRM-triggered outbound calls.
- Use a scheduler for reconciliation, pagination, or knowledge-base synchronization where suitable.
- Treat webhook coverage as selected event coverage rather than a universal change stream.
Objective
Obtain the required Retell AI data and distinguish asynchronous initiation from completion.
Instructions in Martini
- Validate webhook signatures before processing event data.
- Persist the Retell Call identifier immediately after initiating a call.
- Retrieve current Call, transcript, recording reference, or Call Analysis data when the event payload is incomplete.
- Use controlled pagination, polling, or scheduled retrieval for resources without a suitable event.
Objective
Coordinate validation, enrichment, transformation, target writes, and response handling in a maintainable Martini workflow.
Instructions in Martini
- Acknowledge inbound webhooks promptly when longer processing is required.
- Separate event intake from downstream retrieval and application updates where appropriate.
- Apply routing rules for CRM activity, support escalation, notification, or reconciliation paths.
- Use reusable workflow logic for correlation, status normalization, and exception handling.
Objective
Convert Retell AI objects and call payloads into the canonical and target-system models.
Instructions in Martini
- Map Call status, direction, timestamps, Agent ID, Phone Number, transcript, recording reference, and analysis explicitly.
- Normalize timestamps, enumerations, customer identifiers, and empty values before target writes.
- Minimize copied transcript and recording data according to retention and privacy requirements.
- Preserve the Retell Call identifier as a durable external reference.
Objective
Control which calls, agents, numbers, content changes, or analysis outcomes proceed to downstream systems.
Instructions in Martini
- Validate approved Agent and Phone Number identifiers before outbound calls.
- Apply intent, sentiment, extracted-field, or severity rules for support escalation.
- Reject malformed, stale, or unverifiable webhook requests.
- Use environment-specific mappings rather than hard-coded development identifiers.
Common Retell AI data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Agents | Define conversational behavior, prompts, voice configuration, language behavior, and call settings. | Salesforce, HubSpot, configuration stores, internal administration APIs | Martini can provision or retrieve Agents through REST workflows, map environment-specific IDs, validate approved configurations, and avoid hard-coding identifiers across environments. |
| Calls | Represent voice or web calls, including status, timestamps, participants, agent details, transcripts, recordings, latency information, and analysis references. | Salesforce, HubSpot, Zendesk, ServiceNow, operational databases | Martini stores the Retell call ID, receives selected lifecycle events, retrieves complete details when needed, maps fields, and applies idempotency before downstream writes. |
| Phone Numbers | Associate telephone numbers with Agents and inbound or outbound calling configuration. | Retell AI configuration stores, telephony systems, internal administration applications | Martini can synchronize approved number assignments, maintain environment-specific mappings, and validate caller and agent configuration before initiating calls. |
| Knowledge Bases | Provide uploaded or referenced information for agents to use during conversations. | Confluence, SharePoint, document repositories, content stores | Martini can detect source changes, transform supported content and metadata, call the relevant Retell AI knowledge-base operations, and track synchronization status. |
| Voices | Represent voice configurations available for speech synthesis and agent communication. | Agent configuration systems, internal catalogs, administration applications | Martini can retrieve or map Voices when provisioning Agents and enforce approved voice selections through workflow business rules. |
| Call Analysis | Store post-call summaries, classifications, extracted data, or configured custom analysis results. | Salesforce, HubSpot, Zendesk, ServiceNow, analytics databases | Martini can retrieve analysis after completion, normalize classifications and extracted fields, apply escalation rules, and write the result to target systems. |
Authentication and security considerations
Bearer API authentication
Retell AI REST requests use an API key in the Authorization bearer header. Store the key in Martini Secrets Management or protected environment configuration, and use separate credentials for separated development and production projects.
Webhook verification
Inbound Retell AI webhook requests should be validated with the vendor’s documented signature mechanism before event data is accepted. Keep webhook verification secrets separate from API keys.
Voice data protection
- Do not expose API keys or webhook secrets in client-side applications.
- Minimize retention of transcripts, recordings, phone numbers, and other sensitive call data.
- Apply access controls and confirm consent, privacy, residency, and regulatory requirements for the deployment.
Operational considerations for Retell AI integrations
Rate limits and pagination
Confirm account and endpoint limits before processing large call-detail or transcript workloads. Use controlled iteration, throttling, queues, and documented pagination cursors, tokens, or offsets rather than assuming one response contains all objects.
Asynchronous calls
Starting a call does not mean it has completed. Persist the Call identifier, use suitable webhook events as completion signals, and retrieve final details or analysis after processing.
Idempotency and retries
Use the Retell Call identifier and an event-processing store to prevent duplicate CRM activities, tickets, notifications, or billing entries. Retry temporary failures such as throttling, but route malformed payloads and permanent validation failures for review.
Schema and testing
Treat webhook payloads as external contracts, preserve unknown fields where practical, and test status, direction, transcript, recording, and analysis mappings against representative call states. Monitor vendor documentation for event and schema changes.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration instead of isolated scripts
Martini separates webhook intake, API retrieval, transformation, business rules, target writes, and exception handling into maintainable workflows. This is useful when Retell AI data must reach several enterprise applications or when calls continue asynchronously.
Controlled API façade
Martini can expose internal APIs that shield applications from Retell AI credentials, resource identifiers, and vendor-specific payloads while providing a controlled contract for outbound-call requests.
Reusable operational controls
- Centralize secrets, authentication, validation, idempotency, retries, and logging.
- Reuse mappings and workflow logic across CRM, support, notification, and knowledge-base processes.
- Persist checkpoints and synchronization status for reconciliation rather than relying on one-off scripts.
Frequently asked questions
Retell AI can be integrated through its REST APIs for Agents, Calls, Phone Numbers, Knowledge Bases, and call operations, together with selected webhook notifications for call lifecycle and post-call events. Enterprise workflows can retrieve final call details, map transcripts or analysis, and write results to CRM, support, notification, or data-storage systems.
Yes. Martini can consume Retell AI REST APIs, initiate or retrieve calls, expose an HTTP endpoint for Retell AI webhook events, validate signatures, orchestrate asynchronous processing, and map call data into enterprise applications.
No. A dedicated Retell AI connector is not required. Martini can use Retell AI’s documented REST APIs, webhook mechanism, bearer API-key authentication, and knowledge-base endpoints through API-consuming and workflow capabilities.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Retell AI. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Retell AI, telephony providers, infrastructure, or other third-party systems depending on subscription, usage, and deployment model.
Use the Retell AI REST APIs for resource management, outbound or web-call initiation, and retrieval of current call details. Use selected webhook events for call lifecycle and post-call processing, and use scheduled or controlled retrieval for reconciliation and resources without suitable event coverage.
Not necessarily. Retell AI webhook support should be treated as event-specific, with primary coverage around call lifecycle and call-processing events. Martini can use scheduled synchronization or explicit REST requests for resources without an appropriate webhook.
For calls, Martini stores the Call identifier when a call is initiated, receives a suitable completion or analysis event, retrieves the latest details, and updates downstream systems. For Knowledge Bases, Martini can detect source changes, map supported content, call the relevant API, and retain synchronization status for reconciliation.
Martini maps Retell AI fields into canonical and target models, applies validation and business rules, and uses the Retell Call identifier or another durable external key for idempotency. Retryable failures such as temporary throttling can be handled with controlled retries, while malformed events and permanent mapping errors can be routed for investigation.
Related Martini documentation
Workflows
Build a reliable Retell AI integration with Martini
Use Martini to connect Retell AI voice workflows with enterprise applications, enforce security and data rules, and operate asynchronous call processing with consistent monitoring and retry handling.