Skip to main content

FAQ: passing variables to the agent

How does a field from a V2 request get into an agent variable?

The order for each data[] row:
  1. Common fields: phone_number and type never become variables; gender_voice and language go to the agent as variables under their own names.
  2. A schema field with no entry in the map goes as is, under the field name.
  3. An Into a variable entry renames the field to the selected agent variable; Do not pass means the field is not sent.
  4. An empty value takes the entry’s fallback value; with no fallback the key is not passed, and the agent’s default for the variable applies. Order: value from the request → fallback → agent default → empty.
  5. foreign_id reaches the agent only through an Into a variable entry.
  6. The core writes rl_today last — the campaign day as DD.MM.YYYY; it overrides a request field with the same name.
Name matching ignores case, underscores, hyphens and spaces. In the agent, variables are used as {{name}}.Where to look: the campaign card → the contact → the expanded Contact variables row; the call panel → Data → Variables passed to the agent.
Cause 1. The field leads to a variable that the published agent version no longer uses, or the agent was republished after the script was saved: a new publication does not recheck the script. What to do: open the script in the registry, check the summary and the Without a value left panel, and save again.Cause 2. The variable name in the agent and the field name differ in substance (amountDue vs debt_sum). What to do: add an Into a variable entry pointing to the right variable.Cause 3. The value arrived empty, there is no fallback, and the agent has no default. What to do: set a fallback value on the field (only str with a minimum length of 0) or a default for the variable in the agent.
Most often, after a republish the agent has a new signature variable that the script does not cover: the campaign launch is blocked and the request is rolled back.In the cabinet it looks like this: the campaign appears in the list and immediately becomes Cancelled, with no contacts in the dial set. Engineers will see the exact cause in the logs, in the rollback message.What to do: open the script in the registry, map a request field to the variable or add a field with the + field button, save, and ask the client to repeat the request with a new body — repeating the same body within 10 minutes returns the previous response.
By default foreign_id is not passed to the agent. Add an Into a variable entry on the foreign_id field.
rl_today is the campaign day, not the upload date. A request that arrives 5 minutes or less before the end of the campaign day creates a campaign for tomorrow, and rl_today holds tomorrow’s date.If the agent needs the date of the call itself, use the platform variables today or call_date: the platform sets them on every call.
These fields are only variables. The agent chooses the voice and language with its own logic: by branching the flow on {{gender_voice}} and {{language}} or with separate agents for each option. The adapter does not switch them.
The name of the field or of the entry target matches a service column of the contact upload — phone, mobile, cell, msisdn, timezone, the contract group and role headers — or one of the four common fields. Rename the variable in the agent and the entry in the map.
The client gets «#key# does not exist in the format of the request» or «The required field is missing #key#»: the whole request is rejected and nothing is created. The script’s field schema must exactly match the set of keys in the client’s row. Check the order and names against a live request from the client.
See also: Fields and variables.