Conversation Actions: Configure Custom Fields

Add custom fields when an action needs extra information, such as a case number or PO number. 
To each action add the fields needed.

Open: Genesys Cloud → Apps → Mediabriz → Conversation Actions → your action.

For a new action, start with CRM setup or Order and Return setup. Return to that guide after adding the fields.

1. Add and name a field

Under Custom fields (optional), select Add field.

* field_key and Field label are placeholders. Replace them with your own values.

2. Choose visibility and field options

Who can see or edit the field?

* Read-only and hidden values can be set here or read from Genesys participant data.

Text fields

• Default value: an optional starting value for an editable field. With Genesys participant data, this becomes Fallback value (optional).
• Placeholder: a hint inside an empty editable field, up to 80 characters.
• Max length: 1 to 500 characters, default 100. A value of 200 or more gives agents a multi-line box. Line breaks are preserved.
• Required: agents must complete an editable field before sending. With Genesys participant data, Required is available for every visibility. See section 3.

Example: to collect a case number manually, use Key case_number, Label Case number, Type Text, Visibility Agent fills in, and select Required. Notes and PO numbers are also custom fields, not built-in draft fields.

Dropdown fields

• Add 2 to 20 options. Ten or fewer is easier to use.
• Each option needs a unique Label, up to 40 characters, and a unique Key, up to 32 lowercase letters, digits or underscores.
• Your system receives the option key, including in tests. Changing a saved label does not change its key.
• For editable fields, choose no default or a default matching an option key. Optional fields include a blank Optional choice.
• For read-only or hidden fields, select the fixed value to send.

Note:
- Dropdowns cannot use Genesys participant data. 
- Changing a Text field to Dropdown removes its value-source setting.

3. Fill a field from Genesys participant data

Use this when Genesys already has the value, for example a case number set by your flow. Agents do not need to copy it.

Configure the field

1. Choose Text and the required Visibility.
2. Set Value source to Genesys participant data.
3. Enter the Participant data attribute, up to 128 characters. Match its spelling and case exactly. CRM_Case_ID and crm_case_id are different.
4. Optionally add a Fallback value (optional) for conversations without that value.
5. Set Max length. Longer Genesys values are shortened to this limit.
6. Select Required to prevent delivery without a value.

The field Key identifies the value in your system. It can differ from the Genesys attribute name.

Set the value in Genesys first

Mediabriz only reads participant data. Create it using either method:

• Architect: add Set Participant Data to the conversation’s flow, before Transfer to ACD. Use the attribute name entered above.
• API: update the participant attributes. For messaging, use PATCH /api/v2/conversations/messages/{conversationId}/participants/{participantId}/attributes. For email, use /conversations/emails/.

Example API body: {"attributes":{"crm_case_id":"CRM-12345"}}

Check participant data in Genesys Cloud, or call GET /api/v2/conversations/{conversationId} and read participants[].attributes.

Mediabriz checks the customer first, then other participants, newest first after a transfer. The first non-empty value wins. Architect writes to the customer.

What agents see

• Values are read when the window opens. Send Files to CRM also reads them when its file list refreshes.
• Unedited editable fields can refresh. Close and reopen the window if a flow sets a value later.
• Read-only and hidden fields are read again at Send, so the current value or fallback is sent.

If Genesys has no value

Mediabriz uses the backup value you entered in Fallback value (optional). If you left that setting empty, the following rules apply:

The same rules apply if Genesys cannot be read at Send.

Important limits

• Text fields only. Secure participant data is not supported.
• Visitor-controlled Web Messaging attributes starting with context. are not trusted values, even in read-only fields. For account IDs, prices or approvals, have your flow look up and set its own attribute.
• Participant-data values go only to your webhook. Mediabriz does not store them or send them to AI.

Example: use a CRM case number

Your flow sets crm_case_id. Configure the field as follows:

Agents see the case number read-only. Your system receives customFields.case_number. Without a Genesys value or fallback, sending is blocked.

Temporary note: older extensions

Agents need the latest extension for pre-filled values and the From Genesys and Not set in Genesys labels. On older versions:

• Read-only fields show only the fallback or nothing, but send the resolved Genesys value.
• Hidden fields work as described above.
• Editable fields start empty. If left empty, they use Genesys when sent.
• A missing required value shows a general send error.

4. Arrange the fields, save and test

1. Use the field arrows to set the display order.
2. For an existing action, select Save changes. For a new connected action, select Create as disabled while testing.
3. Review Sample webhook payload and run Test webhook with your integration team.

Field limits: up to 10 shown to agents and 20 in total. Aim for five or fewer visible fields.

How fields appear

• Required fields and editable fields with values stay visible.
• Empty optional and read-only fields are grouped under More details · N when there are at least two. The group starts closed; a single field stays visible.
• Required fields shown to agents stay outside the group, including read-only fields missing a required Genesys value.

What the test sends

Test webhook does not read a real conversation. Participant-data fields send their fallback, or SAMPLE- plus the key, such as SAMPLE-case_number.

Real deliveries require a value for every required field. Editable fields can use an agent’s entry; participant-data fields can use Genesys or a fallback. Empty optional fields are omitted. 
See Technical Integration Requirements for the delivery format.