Appointments Routing

This document explains how to control interaction routing when scheduling appointments through the Auvious Appointments UI, the customer widget, or directly via client REST calls. The routing configuration lives under interaction.routing and determines whether the resulting chat/interaction is sent to a Genesys Cloud deployment/flow/queue or to Talkdesk Digital Connect.

v2 vs v1: Use v2 for all new integrations. v2 schedules with a customers array and supports targetAssignment. v1 uses a single customer object and exists only for legacy clients.

Interaction Routing

The interaction object lets the caller influence where and how the chat is routed. It has two parts: routing (platform + routing controls) and customFields (arbitrary key/value data you want carried through for downstream logic).

Routing selection is done via interaction.routing.type. When interaction is present but routing.type is omitted, the server will apply a default based on the Auvious application type (Genesys apps default to a Genesys routing type; Talkdesk apps default to Talkdesk Digital Connect). In addition, the server finalizes routing by injecting or overriding certain routing properties from the Auvious application configuration (for example, Genesys environment configuration), and by ensuring a chatMode exists even if the client omits it. chatMode is client-supplied when provided; if omitted, the server sets a default. If, after server defaults are applied, any required routing inputs are still missing, the request is rejected.

Server-controlled routing properties include:

interaction.routing.properties.pcEnvironment (from the Genesys app configuration)
interaction.routing.properties.deploymentId (when not provided in the request, from the Genesys app configuration)
interaction.routing.properties.touchpointId (when not provided in the request, from the Talkdesk app configuration)

Typical example

{
  "interaction": {
    "routing": {
      "type": "GENESYS_CLOUD_QUEUE",
      "properties": {
        "deploymentId": "c1f80eac-18ed-4178-97ca-dc95db267787",
        "queueName": "queue1",
        "chatMode": "genesys-web-messaging"
      }
    },
    "customFields": {
      "cf1": "cf_value1",
      "cf2": "cf_value2"
    }
  }
}

In the example above, the caller explicitly requests Genesys Cloud queue routing and provides a widget deployment plus queue target. The server will still normalize the final routing configuration by applying any app-configured defaults and overwriting any server-owned properties as needed, then it persists the resolved interaction.routing that will be used when the appointment is launched.

Description and Usage

Name	Type	Description
`interaction.routing`	Object	Contains interaction routing information.
`interaction.routing.type`	Enumeration - type string	Defines the routing type. Supported values: `GENESYS_CLOUD_FLOW`, `GENESYS_CLOUD_QUEUE`, `TALKDESK_DIGITAL_CONNECT`. Default depends on app type: Genesys -> `GENESYS_CLOUD_FLOW`, Talkdesk -> `TALKDESK_DIGITAL_CONNECT`.
`interaction.routing.properties`	Key value pairs - type string	Properties set according to `interaction.routing.type`.
`interaction.routing.properties.chatMode`	String	Routing chat mode. The server always includes it. If omitted, defaults to `genesys-cloud` for Genesys apps or `talkdesk-digital-connect` for Talkdesk apps.

chatMode

Purpose: Determines the chat runtime/channel semantics used by the appointment interaction.
Common values:
- Genesys apps: genesys-cloud, genesys-web-chat, genesys-web-messaging.
- Talkdesk apps: talkdesk-digital-connect.
Validation: The backend requires chatMode to be present and non-empty; it does not enforce a strict enum.
Reference: For more details, see the available chat-mode options in the widget configuration options page.
Behavior:
- If provided in interaction.routing.properties, the value is stored and forwarded as provided.
- If omitted, the server sets the default based on app type:
  - Genesys apps: genesys-cloud
  - Talkdesk apps: talkdesk-digital-connect
Requirements: chatMode is required by backend validation. If you need a specific value, set it explicitly; otherwise the server applies the default for your app type.
Practical guidance: If you are using Genesys Web Messaging in the widget, set chatMode to genesys-web-messaging explicitly. The server default is only safe when you are certain which Genesys runtime the application is configured for.

GENESYS_CLOUD_FLOW

Usage: Connects the widget to an inbound chat flow.
Documentation: For more information, see Inbound Chat Flows Overview.
Note: Not setting a routing:type will default to GENESYS_CLOUD_FLOW.
Required properties: deploymentId, pcEnvironment.
- deploymentId may be provided in the request; if omitted, it is filled from the application configuration.
- pcEnvironment is always sourced from the application configuration; any client value is overwritten. If it is empty in the application config, the request is rejected.

GENESYS_CLOUD_QUEUE

Usage: Connects the widget directly to a specified queue, typically configured as widget type "Version 2".
Note: routing:properties must include a "queueName" when using GENESYS_CLOUD_QUEUE.
Required properties: deploymentId, pcEnvironment, queueName.
- deploymentId may be provided in the request; if omitted, it is filled from the application configuration.
- pcEnvironment is always sourced from the application configuration; any client value is overwritten. If it is empty in the application config, the request is rejected.
- queueName must be present (from assignment or routing properties).

TALKDESK_DIGITAL_CONNECT

Usage: Routes appointments through Talkdesk Digital Connect.
Default: For Talkdesk apps, omitting routing:type defaults to TALKDESK_DIGITAL_CONNECT.
Required properties: touchpointId.
- If provided in the request, that value is used.
- If omitted, the value is taken from the Talkdesk application configuration.
- If neither is available, the request is rejected.

Routing Properties

chatMode may be present for all routing types; defaults are described in the chatMode section above.

GENESYS_CLOUD_FLOW
- deploymentId: Unique identifier for the widget deployment. Defaults to the application settings configuration if not set.
- pcEnvironment: Genesys Cloud environment (required). Sourced from the application configuration and overrides any client-provided value. If it is empty in the application config, the request is rejected.
GENESYS_CLOUD_QUEUE
- deploymentId: Identifies the widget deployment.
- pcEnvironment: Genesys Cloud environment (required). Sourced from the application configuration and overrides any client-provided value. If it is empty in the application config, the request is rejected.
- queueName: Name of the queue for interaction routing.
TALKDESK_DIGITAL_CONNECT
- touchpointId: Talkdesk touchpoint identifier (required). Request value is used; if absent, the Talkdesk app configuration is used. If neither is available, the request is rejected.
- talkdeskAgentId: Derived internally when an appointment is assigned to an agent (from the agent’s Talkdesk profile). If no agent is assigned, this value is not set.

Target assignment

targetAssignment optionally assigns an appointment to a specific agent or queue.

Shape: { "type": "AGENT" | "QUEUE", "id": "<identifier>" }
Genesys behavior:
- QUEUE requires routing.type=GENESYS_CLOUD_QUEUE and sets routing.properties.queueName to the assigned id.
- AGENT requires a non-queue routing type (for example GENESYS_CLOUD_FLOW) and sets routing.properties.agentId to the assigned id.
Talkdesk behavior:
- AGENT is supported; the server derives routing.properties.talkdeskAgentId from the agent profile.
- QUEUE is not supported for Talkdesk apps.
Validation: if targetAssignment conflicts with the routing type, the request is rejected.
Participant requirement: when targetAssignment.type=AGENT, the appointment must include at least one AGENT participant (for example, the organizer or an added agent). If there are no agent participants, scheduling fails.

Custom Fields

interaction.customFields lets you pass arbitrary key/value pairs into the contact-center flow for routing or business logic.

Genesys Architect

Custom fields are exposed to Architect as participant data.

Access pattern: prefix with context.
Example:

{
  "customFields": {
    "field1": "value1"
  }
}

Access in Architect as context.field1.

Talkdesk Studio (Incoming Message Variables)

Incoming Message Variable names cannot contain dots (.). Use underscores (_) instead.

Not allowed: my.custom.property
Allowed: my_custom_property

Example:

{
  "customFields": {
    "my_custom_property": "value1"
  }
}

Examples

v2. Schedule Appointment via Queue with Custom Chat Mode

{
  "applicationId": "7f9ac3e8-0046-4bd7-9638-d82ce0e5c5b6",
  "title": "Video Appointment Test",
  "start": "2022-09-19T16:10:00.000Z",
  "duration": "PT5M",
  "timezone": "Europe/Athens",
  "notes": "Appointment example test...",
  "interaction": {
    "routing": {
      "type": "GENESYS_CLOUD_QUEUE",
      "properties": {
        "deploymentId": "c1f80eac-18ed-4008-97ca-dc95db267787",
        "queueName": "csqDesk",
        "chatMode": "genesys-web-messaging"
      }
    },
    "customFields": {
      "cf1": "cf_value1",
      "cf2": "cf_value2"
    }
  },
  "customers": [
    {
      "username": "bDillon_",
      "name": {
        "firstName": "Bob",
        "lastName": "Dillon"
      },
      "metadata": {
        "refNo": "CS-9838"
      }
    }
  ]
}

v2. Schedule Appointment via Flow with Default Chat Mode

{
  "applicationId": "7f9ac3e8-0046-4bd7-9638-d82ce0e5c5b6",
  "title": "Video Appointment Test",
  "start": "2022-09-19T16:10:00.000Z",
  "duration": "PT5M",
  "timezone": "Europe/Athens",
  "notes": "Appointment example test...",
  "interaction": {
    "routing": {
      "type": "GENESYS_CLOUD_FLOW",
      "properties": {
        "deploymentId": "497d1b49-2c97-458a-a6c2-aaccd468b56e"
      }
    },
    "customFields": {
      "cf1": "cf_value1",
      "cf2": "cf_value2"
    }
  },
  "customers": [
    {
      "username": "bDillon_",
      "name": {
        "firstName": "Bob",
        "lastName": "Dillon"
      },
      "metadata": {
        "refNo": "CS-9838"
      }
    }
  ]
}

v2. Talkdesk Digital Connect

{
  "applicationId": "7f9ac3e8-0046-4bd7-9638-d82ce0e5c5b6",
  "title": "Talkdesk Appointment",
  "start": "2022-09-19T16:10:00.000Z",
  "duration": "PT5M",
  "timezone": "Europe/Athens",
  "notes": "Appointment example test...",
  "interaction": {
    "routing": {
      "type": "TALKDESK_DIGITAL_CONNECT",
      "properties": {
        "touchpointId": "tp-123"
      }
    },
    "customFields": {
      "cf1": "cf_value1",
      "cf2": "cf_value2"
    }
  },
  "targetAssignment": {
    "type": "AGENT",
    "id": "agent-uuid"
  },
  "customers": [
    {
      "username": "bDillon_",
      "name": {
        "firstName": "Bob",
        "lastName": "Dillon"
      },
      "metadata": {
        "refNo": "CS-9838"
      }
    }
  ]
}

Legacy v1. Schedule Appointment via Queue with Custom Chat Mode

{
  "applicationId": "7f9ac3e8-0046-4bd7-9638-d82ce0e5c5b6",
  "title": "Video Appointment Test",
  "start": "2022-09-19T16:10:00.000Z",
  "duration": "PT5M",
  "timezone": "Europe/Athens",
  "notes": "Appointment example test...",
  "interaction": {
    "routing": {
      "type": "GENESYS_CLOUD_QUEUE",
      "properties": {
        "deploymentId": "c1f80eac-18ed-4178-97ca-dc95db267787",
        "queueName": "csqDesk",
        "chatMode": "genesys-web-messaging"
      }
    },
    "customFields": {
      "cf1": "cf_value1",
      "cf2": "cf_value2"
    }
  },
  "customer": {
    "username": "bDillon_",
    "name": {
      "firstName": "Bob",
      "lastName": "Dillon"
    },
    "metadata": {
      "refNo": "CS-9838"
    }
  }
}

Legacy v1. Schedule Appointment via Flow with Default Chat Mode

{
  "applicationId": "7f9ac3e8-0046-4bd7-9638-d82ce0e5c5b6",
  "title": "Video Appointment Test",
  "start": "2022-09-19T16:10:00.000Z",
  "duration": "PT5M",
  "timezone": "Europe/Athens",
  "notes": "Appointment example test...",
  "interaction": {
    "routing": {
      "type": "GENESYS_CLOUD_FLOW",
      "properties": {
        "deploymentId": "497d1b49-2c97-458a-a6c2-aaccd468b56e"
      }
    },
    "customFields": {
      "cf1": "cf_value1",
      "cf2": "cf_value2"
    }
  },
  "customer": {
    "username": "bDillon_",
    "name": {
      "firstName": "Bob",
      "lastName": "Dillon"
    },
    "metadata": {
      "refNo": "CS-9838"
    }
  }
}

Appointments Routing

Interaction Routing​

Typical example​

Description and Usage​

chatMode​

GENESYS_CLOUD_FLOW​

GENESYS_CLOUD_QUEUE​

TALKDESK_DIGITAL_CONNECT​

Routing Properties​

Target assignment​

Custom Fields​

Genesys Architect​

Talkdesk Studio (Incoming Message Variables)​

Examples​

v2. Schedule Appointment via Queue with Custom Chat Mode​

v2. Schedule Appointment via Flow with Default Chat Mode​

v2. Talkdesk Digital Connect​

Legacy v1. Schedule Appointment via Queue with Custom Chat Mode​

Legacy v1. Schedule Appointment via Flow with Default Chat Mode​