Voice agentsAgents

Create agent

Creates an agent. The system prompt is generated from description, industry, designation, company_name, tone, guardrails and conversation_flow, so the call can take a few seconds.

POST/v2/agents

If you've connected your own provider keys on the Providers page, the agent uses them automatically for the matching LLM, STT and TTS providers.

Returns 402 when your plan's agent limit is reached.

Authorization

Authorizationstringheaderrequired
Bearer authentication header of the form Bearer <api_key>, where <api_key> is a key from Account Settings → API keys in your dashboard.

Request body

application/json

agent_namestringrequired
Name the agent introduces itself with.
llm_providerstringrequired
LLM provider for voice calls.
Allowed:openaianthropicgooglegrokopenrouterazure
llm_modelstringrequired
LLM model id, e.g. gpt-4o-mini.
stt_providerstringrequired
Speech-to-text provider.
Allowed:deepgramopenai
stt_modelstringrequired
Speech-to-text model, e.g. nova-3.
tts_providerstringrequired
Text-to-speech provider.
Allowed:sarvamelevenlabssmallestcartesiarimeinworldazuretts
tts_voicestringrequired
Voice id from the TTS provider.
descriptionstring
Short goal of the agent. Drives the generated system prompt.
Default: ""
industrystring
Industry context.
Default: ""
designationstring
Role the agent plays.
Default: ""
company_namestring
Company the agent speaks on behalf of.
Default: ""
languagestring
Conversation language, e.g. english, hindi, hinglish, tamil. Must be supported by the STT provider.
Default: english
llm_temperaturenumber
Sampling temperature.
Default: 0.7
llm_max_tokeninteger
Max tokens per reply.
Default: 350
whatsapp_llm_providerstring
LLM provider for the WhatsApp text agent.
whatsapp_llm_modelstring
LLM model for the WhatsApp text agent.
whatsapp_llm_temperaturenumber
Temperature for WhatsApp replies.
Default: 0.7
whatsapp_llm_max_tokeninteger
Max tokens per WhatsApp reply.
Default: 350
tts_modelstring
TTS model, when the provider has several.
tts_languagestring
TTS language code.
Default: en
tonestring
Speaking tone.
Default: Warm & professional
greeting_messagestring
First line on inbound calls.
Default: ""
outbound_greeting_messagestring
First line on outbound calls.
Default: ""
guardrailsstring
Rules the agent must follow.
Default: ""
conversation_flowstring[]
Ordered conversation steps.
Default: []
closing_messagestring
Line used to close the call.
Default: ""
hangup_promptstring
When the agent should end the call.
background_soundstring
Ambience under the voice.
Allowed:noneoffice_ambienceDefault: none
set_inbound_numberstring
One of your phone numbers (E.164) to route inbound calls to this agent.
set_inbound_whatsapp_numberstring
One of your WhatsApp phone_number_ids whose messages this agent answers.

Response

The created agent object.

Show all 45 fieldsHide fields

idstring (uuid)
Unique identifier of the agent.
tenant_idstring (uuid)
The workspace that owns the agent.
agent_namestring
Name the agent introduces itself with.
descriptionstring
Short goal of the agent, used to compose the system prompt.
system_promptstringnullable
The full prompt sent to the LLM. Generated on create; afterwards stored exactly as you send it.
industrystring
Industry context, e.g. Banking.
designationstring
Role the agent plays, e.g. Loan advisor.
company_namestring
Company the agent speaks on behalf of.
llm_providerstring
LLM provider for voice calls.
Allowed:openaianthropicgooglegrokopenrouterazure
llm_modelstring
LLM model id, e.g. gpt-4o-mini.
llm_temperaturenumber
Sampling temperature.
Default: 0.7
llm_max_tokeninteger
Max tokens per LLM reply.
Default: 350
whatsapp_llm_providerstringnullable
LLM provider for the WhatsApp text agent.
whatsapp_llm_modelstringnullable
LLM model for the WhatsApp text agent.
whatsapp_llm_temperaturenumber
Temperature for the WhatsApp text agent.
Default: 0.7
whatsapp_llm_max_tokeninteger
Max tokens per WhatsApp reply.
Default: 350
stt_providerstring
Speech-to-text provider.
Allowed:deepgramopenai
stt_modelstring
Speech-to-text model, e.g. nova-3.
tts_providerstring
Text-to-speech provider.
Allowed:sarvamelevenlabssmallestcartesiarimeinworldazuretts
tts_voicestring
Voice id from the TTS provider.
tts_modelstringnullable
TTS model, when the provider has several.
tts_languagestring
TTS language code.
Default: en
languagestringnullable
Conversation language, e.g. english, hindi, hinglish, tamil. Must be supported by the STT provider.
stt_lang_codestringnullable
Read-only. Language code derived from language and the STT provider.
llm_credential_idstring (uuid)nullable
Read-only. Your own LLM key (from Providers) used for this agent, if connected.
stt_credential_idstring (uuid)nullable
Read-only. Your own STT key used for this agent, if connected.
tts_credential_idstring (uuid)nullable
Read-only. Your own TTS key used for this agent, if connected.
tonestring
Speaking tone.
Default: Warm & professional
greeting_messagestring
First line spoken on inbound calls.
outbound_greeting_messagestring
First line spoken on outbound calls.
guardrailsstring
Rules the agent must follow.
conversation_flowstring[]
Ordered steps of the conversation.
closing_messagestring
Line used to close the call.
hangup_promptstringnullable
When the agent should end the call.
background_soundstring
Ambience mixed under the voice.
Allowed:noneoffice_ambienceDefault: none
number_idstring (uuid)nullable
Read-only. Phone number linked for inbound calls.
set_inbound_numberstringnullable
Phone number (E.164) that routes inbound calls to this agent.
whatsapp_account_idstring (uuid)nullable
Read-only. WhatsApp account linked to this agent.
set_inbound_whatsapp_numberstringnullable
WhatsApp phone_number_id whose messages this agent answers.
post_call_whatsapp_template_namestringnullable
Read-only. WhatsApp template sent after a call.
post_call_whatsapp_template_languagestringnullable
Read-only. Language of the post-call template.
post_call_whatsapp_template_paramsstring[]
Read-only. Variables filled into the post-call template.
is_activeboolean
Whether the agent answers calls and messages.
Default: true
created_atstring (date-time)
When the agent was created.
updated_atstring (date-time)
When the agent was last changed.

curl --request POST \ --url 'https://api.tarangnow.com/v2/agents' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Type: application/json' \ --data '{ "agent_name": "Priya", "description": "Qualify inbound home-loan leads and book a callback with an advisor.", "industry": "Banking", "designation": "Loan advisor", "company_name": "Acme Finance", "language": "english", "llm_provider": "openai", "llm_model": "gpt-4o-mini", "stt_provider": "deepgram", "stt_model": "nova-3", "tts_provider": "elevenlabs", "tts_voice": "21m00Tcm4TlvDq8ikWAM", "greeting_message": "Hi, this is Priya from Acme Finance. How can I help you today?", "guardrails": "Never quote final interest rates. Never ask for OTPs or passwords.", "conversation_flow": [ "Greet and confirm the caller'\''s name", "Ask about the loan amount and city", "Offer a callback slot" ], "set_inbound_number": "+918031234567" }'

{ "id": "3f6c2b1e-8a4d-4c5e-9b2a-1d7e6f8a9b0c", "tenant_id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "number_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a", "whatsapp_account_id": null, "system_prompt": "#SECTION 1: IDENTITY AND DEMEANOUR\n\nAgent Name: Priya\nGender: Female\n\nPriya is a loan advisor on behalf of Acme Finance in the banking industry...", "description": "Qualify inbound home-loan leads and book a callback with an advisor.", "agent_name": "Priya", "industry": "Banking", "designation": "Loan advisor", "company_name": "Acme Finance", "llm_provider": "openai", "llm_model": "gpt-4o-mini", "llm_temperature": 0.7, "llm_max_token": 350, "llm_credential_id": null, "whatsapp_llm_provider": "openai", "whatsapp_llm_model": "gpt-4o-mini", "whatsapp_llm_temperature": 0.7, "whatsapp_llm_max_token": 350, "stt_provider": "deepgram", "stt_model": "nova-3", "stt_credential_id": null, "tts_provider": "elevenlabs", "tts_voice": "21m00Tcm4TlvDq8ikWAM", "tts_model": "eleven_flash_v2_5", "tts_language": "en", "tts_credential_id": null, "tone": "Warm & professional", "greeting_message": "Hi, this is Priya from Acme Finance. How can I help you today?", "outbound_greeting_message": "", "guardrails": "Never quote final interest rates. Never ask for OTPs or passwords.", "conversation_flow": [ "Greet and confirm the caller's name", "Ask about the loan amount and city", "Offer a callback slot" ], "closing_message": "Thanks for calling Acme Finance. Have a great day!", "hangup_prompt": null, "background_sound": "none", "set_inbound_number": "+918031234567", "set_inbound_whatsapp_number": null, "post_call_whatsapp_template_name": null, "post_call_whatsapp_template_language": null, "post_call_whatsapp_template_params": [], "language": "english", "stt_lang_code": "en-IN", "is_active": true, "created_at": "2026-10-20T09:15:42.120Z", "updated_at": "2026-10-24T14:03:11.508Z" }

Request body

application/json

agent_namestringrequired

Name the agent introduces itself with.

llm_providerstringrequired

LLM provider for voice calls.

Allowed:openaianthropicgooglegrokopenrouterazure

llm_modelstringrequired

LLM model id, e.g. gpt-4o-mini.

stt_providerstringrequired

Speech-to-text provider.

Allowed:deepgramopenai

stt_modelstringrequired

Speech-to-text model, e.g. nova-3.

tts_providerstringrequired

Text-to-speech provider.

Allowed:sarvamelevenlabssmallestcartesiarimeinworldazuretts

tts_voicestringrequired

Voice id from the TTS provider.

descriptionstring

Short goal of the agent. Drives the generated system prompt.

Default: ""

industrystring

Industry context.

Default: ""

designationstring

Role the agent plays.

Default: ""

company_namestring

Company the agent speaks on behalf of.

Default: ""

languagestring

Conversation language, e.g. english, hindi, hinglish, tamil. Must be supported by the STT provider.

Default: english

llm_temperaturenumber

Sampling temperature.

Default: 0.7

llm_max_tokeninteger

Max tokens per reply.

Default: 350

whatsapp_llm_providerstring

LLM provider for the WhatsApp text agent.

whatsapp_llm_modelstring

LLM model for the WhatsApp text agent.

whatsapp_llm_temperaturenumber

Temperature for WhatsApp replies.

Default: 0.7

whatsapp_llm_max_tokeninteger

Max tokens per WhatsApp reply.

Default: 350

tts_modelstring

TTS model, when the provider has several.

tts_languagestring

TTS language code.

Default: en

tonestring

Speaking tone.

Default: Warm & professional

greeting_messagestring

First line on inbound calls.

Default: ""

outbound_greeting_messagestring

First line on outbound calls.

Default: ""

guardrailsstring

Rules the agent must follow.

Default: ""

conversation_flowstring[]

Ordered conversation steps.

Default: []

closing_messagestring

Line used to close the call.

Default: ""

hangup_promptstring

When the agent should end the call.

background_soundstring

Ambience under the voice.

Allowed:noneoffice_ambienceDefault: none

set_inbound_numberstring

One of your phone numbers (E.164) to route inbound calls to this agent.

set_inbound_whatsapp_numberstring

One of your WhatsApp phone_number_ids whose messages this agent answers.

Response

The created agent object.

Show all 45 fieldsHide fields

idstring (uuid)
Unique identifier of the agent.
tenant_idstring (uuid)
The workspace that owns the agent.
agent_namestring
Name the agent introduces itself with.
descriptionstring
Short goal of the agent, used to compose the system prompt.
system_promptstringnullable
The full prompt sent to the LLM. Generated on create; afterwards stored exactly as you send it.
industrystring
Industry context, e.g. Banking.
designationstring
Role the agent plays, e.g. Loan advisor.
company_namestring
Company the agent speaks on behalf of.
llm_providerstring
LLM provider for voice calls.
Allowed:openaianthropicgooglegrokopenrouterazure
llm_modelstring
LLM model id, e.g. gpt-4o-mini.
llm_temperaturenumber
Sampling temperature.
Default: 0.7
llm_max_tokeninteger
Max tokens per LLM reply.
Default: 350
whatsapp_llm_providerstringnullable
LLM provider for the WhatsApp text agent.
whatsapp_llm_modelstringnullable
LLM model for the WhatsApp text agent.
whatsapp_llm_temperaturenumber
Temperature for the WhatsApp text agent.
Default: 0.7
whatsapp_llm_max_tokeninteger
Max tokens per WhatsApp reply.
Default: 350
stt_providerstring
Speech-to-text provider.
Allowed:deepgramopenai
stt_modelstring
Speech-to-text model, e.g. nova-3.
tts_providerstring
Text-to-speech provider.
Allowed:sarvamelevenlabssmallestcartesiarimeinworldazuretts
tts_voicestring
Voice id from the TTS provider.
tts_modelstringnullable
TTS model, when the provider has several.
tts_languagestring
TTS language code.
Default: en
languagestringnullable
Conversation language, e.g. english, hindi, hinglish, tamil. Must be supported by the STT provider.
stt_lang_codestringnullable
Read-only. Language code derived from language and the STT provider.
llm_credential_idstring (uuid)nullable
Read-only. Your own LLM key (from Providers) used for this agent, if connected.
stt_credential_idstring (uuid)nullable
Read-only. Your own STT key used for this agent, if connected.
tts_credential_idstring (uuid)nullable
Read-only. Your own TTS key used for this agent, if connected.
tonestring
Speaking tone.
Default: Warm & professional
greeting_messagestring
First line spoken on inbound calls.
outbound_greeting_messagestring
First line spoken on outbound calls.
guardrailsstring
Rules the agent must follow.
conversation_flowstring[]
Ordered steps of the conversation.
closing_messagestring
Line used to close the call.
hangup_promptstringnullable
When the agent should end the call.
background_soundstring
Ambience mixed under the voice.
Allowed:noneoffice_ambienceDefault: none
number_idstring (uuid)nullable
Read-only. Phone number linked for inbound calls.
set_inbound_numberstringnullable
Phone number (E.164) that routes inbound calls to this agent.
whatsapp_account_idstring (uuid)nullable
Read-only. WhatsApp account linked to this agent.
set_inbound_whatsapp_numberstringnullable
WhatsApp phone_number_id whose messages this agent answers.
post_call_whatsapp_template_namestringnullable
Read-only. WhatsApp template sent after a call.
post_call_whatsapp_template_languagestringnullable
Read-only. Language of the post-call template.
post_call_whatsapp_template_paramsstring[]
Read-only. Variables filled into the post-call template.
is_activeboolean
Whether the agent answers calls and messages.
Default: true
created_atstring (date-time)
When the agent was created.
updated_atstring (date-time)
When the agent was last changed.