Skip to content
Voicebot

Resolve an inbound call to its run envelope

GET
/v1/internal/communication/resolve
curl --request GET \
  --url 'https://example.com/v1/internal/communication/resolve?caller=example&callee=example'

Given the dialed identifier, resolves the owning agent globally, loads its scenario, creates an inbound communication, and returns the shared CommunicationEnvelope hermes runs the call off. A malformed identifier → 400; no agent or scenario → 404 (no communication is created). Called by hermes inbound wiring.

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
caller
required
string
/^[a-zA-Z0-9]/

The external party that called us (the non-voicebot number); recorded as the communication recipient. Must start with a letter or digit.

callee
required
string
/^[a-zA-Z0-9]/

Our dialed identifier (DID/number) the call came in on; resolves the owning agent. Must start with a letter or digit.

Responses

Section titled “Responses”

200

Section titled “200”

Resolved run envelope.

Media typeapplication/json

The shared run envelope, identical for both directions: the inbound resolve response and the outbound originate request body [T4]. hermes runs inbound and outbound off this one contract.

object
communication
required
object
id
required
string
account_sid
required
string
agent_sid
required
string
scenario_sid
required

Scenario the communication runs; empty on legacy rows created before the scenario binding was recorded.

string
strategy_sid
required
string
nullable
version
required

Published scenario version; null when the run used a draft.

integer
nullable
draft_version
required

Draft scenario version; null when the run used a published version. Exactly one of version / draft_version is set.

integer
nullable
strategy_attempt_sid
required
string
nullable
strategy_attempt_number
required
integer
recipient
required
string
direction
required
string
Allowed values: inbound outbound
communication_status
required
string
Allowed values: new ready dialing in_progress bounced done failed drifted
call_status
required
string
Allowed values: busy rejected no_answer voicemail incomplete completed failed tech_canceled
reason
required
string
data
required
object
key
additional properties
any
variables
required
object
key
additional properties
any
status_history
required
Array<object>
nullable
object
from
required
string
to
required
string
reason
string
call_sid
string
at
required
string format: date-time
scheduled_at
required
string format: date-time
nullable
schedule
required
object
key
additional properties
any
timezone
required
string
next_call_at
required
string format: date-time
call_attempt_number
required
integer
executor_id
required
string
nullable
call_sid
required
string
nullable
duration
required

Call duration in seconds, measured by the execution layer; 0 until the call completes.

integer
is_test
required

Whether this is a test communication.

boolean
consent_granted
required

Whether personal-data recording consent was granted for the call.

boolean
has_recording
required

Whether a stored call recording exists for this communication.

boolean
has_call_history
required

Whether a saved call execution history exists for this communication.

boolean
created_at
required
string format: date-time
updated_at
required
string format: date-time
agent
required
object
id
required
string
account_sid
required
string
gateway_type
required

Selects the gateway kind; the matching sid (number_sid / number_pool_sid) must be set and the other empty (422 otherwise).

string
Allowed values: number number_pool
number_sid
required
string
nullable
number_pool_sid
required
string
nullable
scenario_sid
required
string
voicemail_enabled
required
boolean
call_recording
required
boolean
calling_schedule
required
object
strategy

Schedule strategy

string
args

Strategy args (free-form)

object
key
additional properties
any
timezone
required
string
limits
required
object
cps
integer
cpl
integer
is_test
required
boolean
communication_result
required
object
targets
Array<object>
object
url
string
sms
required
object
provider_sid
required
string
use_alpha
boolean
alpha

Required when use_alpha is true; one of the provider’s alphas.

string
number

Required when use_alpha is false; one of the provider’s numbers.

string
status
required
string
Allowed values: active inactive
archive_time
required
string format: date-time
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time
scenario
required
object
id
required
string
type
required
string
Allowed values: constructor
name
required
string
template
required
string
description
required
string
account_sid
required
string
constructor
required
object
bricks
object
audio
object
v1
Array<object>
object
id
required
string
description
string
properties
object
play_mode
string
audios
Array<object>
object
mode
string
tts_properties
object
text
string
file_properties
object
url
string
tts_general
object
language
string
voice
string
engine
string
speed
number format: float
model
string
outputs
Array<object>
object
type
string
description
string
audio_file
object
v1
Array<object>
object
id
required
string
description
string
properties
object
url
string
outputs
Array<object>
object
type
string
description
string
audio_tts
object
v1
Array<object>
object
id
required
string
description
string
properties
object
text
string
language
string
voice
string
engine
string
model
string
outputs
Array<object>
object
type
string
description
string
sms
object
v1
Array<object>
object
id
required
string
description
string
properties

Message content only. Provider, credentials, and sender identity resolve from the agent’s SMS settings at send time.

object
to

Recipient override; empty means the communication recipient.

string
text
string
outputs
Array<object>
object
type
string
description
string
goal
object
v1
Array<object>
object
id
required
string
description
string
properties
object
goal
string
outputs
Array<object>
object
type
string
description
string
end_call
object
v1
Array<object>
object
id
required
string
description
string
properties
object
signal
string
outputs
Array<object>
object
type
string
description
string
assignment
object
v1
Array<object>
object
id
required
string
description
string
properties
object
variables
Array<object>
object
name
string
value
string
outputs
Array<object>
object
type
string
description
string
increment
object
v1
Array<object>
object
id
required
string
description
string
properties
object
variables
Array<object>
object
variable
string
outputs
Array<object>
object
type
string
description
string
condition_group
object
v1
Array<object>
object
id
required
string
description
string
properties
object
condition
object
conditions
Array<object>
object
condition_id
string
description
string
condition_operator
string
elements
Array<object>
object
variable
string
element_operator
string
value
string
outputs
Array<object>
object
type
string
description
string
start_tree
object
v1
Array<object>
object
id
required
string
description
string
properties
object
outputs
Array<object>
object
type
string
description
string
start_call
object
v1
Array<object>
object
id
required
string
description
string
properties
object
stt_general
object
language
string
engine
string
model
string
primary_language
string
fallback_languages
Array<string>
tts_general
object
language
string
voice
string
engine
string
speed
number format: float
model
string
outputs
Array<object>
object
type
string
description
string
outbound_call
object
v1
Array<object>
object
id
required
string
description
string
properties
object
is_voicemail
boolean
outputs
Array<object>
object
type
string
description
string
inbound_call
object
v1
Array<object>
object
id
required
string
description
string
properties
object
outputs
Array<object>
object
type
string
description
string
end
object
v1
Array<object>
object
id
required
string
description
string
properties
object
outputs
Array<object>
object
type
string
description
string
call_transfer
object
v1
Array<object>
object
id
required
string
description
string
properties
object
from
string
number
string
message_to_manager
object
mode
string
tts
object
text
string
file
object
url
string
message_to_client
object
mode
string
tts
object
text
string
file
object
url
string
timeout
integer
tts_properties
object
language
string
voice
string
engine
string
model
string
sip_header
object
sip_headers
Array<object>
object
name
string
value
string
transfer_mode
string
outputs
Array<object>
object
type
string
description
string
question
object
v1
Array<object>
object
id
required
string
description
string
properties
object
tts_properties
object
language
string
voice
string
engine
string
speed
number format: float
model
string
dtmf_properties
object
dtmf_timeout
number format: float
no_input_timeout
number format: float
min_symbols
integer
max_symbols
integer
finish_on_key
string
stt_properties
object
speech_timeout
number format: float
no_input_timeout
number format: float
language
string
recognition_shift
object
direction
string
duration
number format: float
engine
string
grammar_parameter
object
parameters
Array<object>
object
key
string
value
string
class_token
object
tokens
Array<string>
filter
object
filters
Array<string>
tokens
Array<string>
intent_properties
object
classifier

The classifier a question brick classifies against.

object
id
string
version

Classifier version this brick classifies against. Always written explicitly; 0 means the classifier as the unversioned surface serves it.

integer
llm_properties
object
engine
string
model
string
messages
Array<object>
object
role
string
content
string
temperature
number format: float
provider
string
gdpr_required
boolean
threshold
number format: float
timezone
string
recognition_mode
string
enable_voice_activity_detection
boolean
interruptible_dialog
boolean
interruption_shift
object
direction
string
duration
number format: float
model
string
primary_language
string
fallback_languages
Array<string>
statement
object
audio
object
mode
string
tts
object
text
string
file
object
url
string
is_interruptible
boolean
type
string
input_mode
string
answer
object
answers
Array<object>
object
answer_id
string
description
string
speech_input
object
tokens
Array<string>
mode
string
intent
object
id
string
entity
object
entities
Array<object>
object
type
string
variable
object
name
string
dtmf_input
object
value
string
tag
string
fallback_invalid
object
fallbacks
Array<object>
object
is_repeat_statement
boolean
audio
object
mode
string
tts
object
text
string
file
object
url
string
is_interruptible
boolean
type
string
llm_properties
object
engine
string
model
string
messages
Array<object>
object
role
string
content
string
temperature
number format: float
provider
string
gdpr_required
boolean
entity
object
entities
Array<object>
object
type
string
variable
object
name
string
fallback_empty
object
fallbacks
Array<object>
object
is_repeat_statement
boolean
audio
object
mode
string
tts
object
text
string
file
object
url
string
is_interruptible
boolean
type
string
llm_properties
object
engine
string
model
string
messages
Array<object>
object
role
string
content
string
temperature
number format: float
provider
string
gdpr_required
boolean
entity
object
entities
Array<object>
object
type
string
variable
object
name
string
outputs
Array<object>
object
type
string
description
string
webhook
object
v1
Array<object>
object
id
required
string
description
string
properties
object
request
object
method
string
url
string
body
object
data
string
type
string
form_values
Array<object>
object
name
string
value
string
authentication
object
type
string
basic
object
username
string
password
string
bearer
object
token
string
header
object
headers
Array<object>
object
name
string
value
string
insecure_skip_verify
boolean
proxy
object
url
string
attach_call_metadata
boolean
timeout
number format: float
options
object
async
boolean
timeout
number format: float
response_mapping
object
variables
Array<object>
object
name

Target variable, written as a placeholder. Returned unwrapped in variables.

string
/^\{\{[A-Za-z0-9\-_.]+\}\}$/
source

Where the value is read from — body (JSONPath in path) or header (header name in path).

string
path
string
set_if_not_found
string
outputs
Array<object>
object
type
string
description
string
data_mapping
object
v1
Array<object>
object
id
required
string
description
string
properties
object
input
string
variables
Array<object>
object
name
string
path
string
set_if_not_found
string
outputs
Array<object>
object
type
string
description
string
tree
object
v1
Array<object>
object
id
required
string
description
string
properties
object
tree
object
id
string
outputs
Array<object>
object
type
string
description
string
end_tree
object
v1
Array<object>
object
id
required
string
description
string
properties
object
output
object
type
string
description
string
outputs
Array<object>
object
type
string
description
string
background_audio
object
v1
Array<object>
object
id
required
string
description
string
properties
object
audio
object
audios
Array<object>
object
mode
string
file_properties
object
url
string
volume
integer
outputs
Array<object>
object
type
string
description
string
javascript
object
v1
Array<object>
object
id
required
string
description
string
properties
object
source
string
outputs
Array<object>
object
type
string
description
string
v2
Array<object>
object
id
string
description
string
properties
object
url
string
input_variables
Array<string>
outputs
Array<object>
object
type
string
description
string
warm_up_tts
object
v1
Array<object>
object
id
required
string
description
string
properties
object
brick
object
bricks
Array<object>
object
id
string
type
string
outputs
Array<object>
object
type
string
description
string
business_metric
object
v1
Array<object>
object
id
required
string
description
string
properties
object
key
string
value
string
outputs
Array<object>
object
type
string
description
string
ai_agent
object
v1
Array<object>
object
id
required
string
description
required
string
properties
object
prompts
object
restrictions
object
content
string
role
object
content
string
initial_phrase
object
content
string
is_interruptible
boolean
skill
object
skills
Array<object>
object
id
required
string
name
string
function_name
string
description
required
string
parameters
object
type
string
properties
object
key
additional properties
object
type
string
description
string
variable_name
string
enum
Array<string>
default
string
required
Array<string>
additional_properties
boolean
knowledge_base
object
type
string
prompt
object
content
string
rag
object
document
object
ids
Array<string>
number
integer
threshold
number format: float
fallbacks
object
error
object
counter
integer
empty
object
counter
integer
configuration
object
llm
object
engine
string
model
string
temperature
number format: float
max_tokens
integer
provider
string
gdpr_required
boolean
tts
object
language
string
voice
string
engine
string
speed
number format: float
model
string
stt
object
speech_timeout
number format: float
no_input_timeout
number format: float
language
string
recognition_shift
object
direction
string
duration
number format: float
engine
string
grammar_parameter
object
parameters
Array<object>
object
key
string
value
string
class_token
object
tokens
Array<string>
filter
object
filters
Array<string>
tokens
Array<string>
intent_properties
object
classifier

The classifier a question brick classifies against.

object
id
string
version

Classifier version this brick classifies against. Always written explicitly; 0 means the classifier as the unversioned surface serves it.

integer
llm_properties
object
engine
string
model
string
messages
Array<object>
object
role
string
content
string
temperature
number format: float
provider
string
gdpr_required
boolean
threshold
number format: float
timezone
string
recognition_mode
string
enable_voice_activity_detection
boolean
interruptible_dialog
boolean
interruption_shift
object
direction
string
duration
number format: float
model
string
primary_language
string
fallback_languages
Array<string>
dialog
object
context_mode
string
max_turns
integer
outputs
Array<object>
object
type
string
description
string
send_dtmf
object
v1
Array<object>
object
id
required
string
description
required
string
properties
object
digits
string
interval
integer
duration
integer
outputs
Array<object>
object
type
string
description
string
recording_setup
object
v1
Array<object>
object
id
required
string
description
required
string
properties
object
outputs
Array<object>
object
type
string
description
string
transcription
object
v1
Array<object>
object
id
required
string
description
required
string
properties
object
request
object
requests
Array<object>
object
source
object
type
string
url
string
engine
string
prompt
string
model
string
outputs
Array<object>
object
type
string
description
string
forest
object
trees
Array<object>
object
description
string
tree_id
string
nodes
Array<object>
object
id
string
brick
object
id
string
type
string
version
string
links
Array<object>
object
output_type
string
reference
object
tree_id
string
node_id
string
return
object
tree_id
string
node_id
string
properties
object
engine_version
string
fix_communication_ttl
required
integer
is_shared_for_copy
required

Shares the scenario for read and copy with other accounts of the owning tenant; the read capability is still required. Outside the owning tenant the scenario reads as absent (404). Never affects list surfaces or writes.

boolean
created_at
required
string format: date-time
updated_at
required
string format: date-time
version
required
integer
draft_exists
required
boolean
trunk
required

The trunk the call routes through — the first live trunk of the call’s tenant (resolved via the communication’s account). Null when the tenant has no trunk configured; the execution layer then falls back to its default trunk.

object
sid
required
string
name
required
string
caller
required

The SIP From party’s resolved gateway. Direction-relative: on outbound this is our number (the outbound from); on inbound the From is the external caller, so this is null and the caller is communication.recipient.

object
id
required
string
account_sid
required
string
identifier
required
string
name
required
string
pool_sid
required
string
nullable
status
required
string
Allowed values: active inactive
created_at
required
string format: date-time
updated_at
required
string format: date-time
callee
required

The SIP To party’s resolved gateway. Direction-relative: on inbound this is our number; on outbound the To is the external party, so this is null and the callee is communication.recipient.

object
id
required
string
account_sid
required
string
identifier
required
string
name
required
string
pool_sid
required
string
nullable
status
required
string
Allowed values: active inactive
created_at
required
string format: date-time
updated_at
required
string format: date-time
Example
{
  "communication": {
    "direction": "inbound",
    "communication_status": "new",
    "call_status": "busy"
  },
  "agent": {
    "gateway_type": "number",
    "status": "active"
  },
  "scenario": {
    "type": "constructor"
  },
  "caller": {
    "status": "active"
  },
  "callee": {
    "status": "active"
  }
}

400

Section titled “400”

Missing or malformed identifier (must start with a letter or digit).

404

Section titled “404”

No agent or scenario resolvable for the identifier — rejected, no row created.