Interaction routing

Use interaction routing when you need explicit control over how the contact-center interaction is resolved at appointment scheduling time.

An "interaction" is the contact-center platform interaction created alongside the appointment. Routing is configured under interaction.routing and determines whether the interaction is handled by Genesys Cloud (FLOW/QUEUE) or Talkdesk Digital Connect.

Schedule endpoints:

• v2: Schedule Appointment (v2)
• v1 (Deprecated reference): Schedule Appointment (v1)

v1 is deprecated and should be avoided for new integrations. Keep v1 usage only for existing integrations during migration to v2.

Version usage

Use v2 for all new integrations.

• v2 uses a customers array and supports targetAssignment.
• v2 is the active contract for routing enhancements.

Use v1 only as a deprecated reference path for existing integrations.

• v1 uses a single customer object.
• Migrate to v2 for all ongoing development.

Migration note

Key v1 -> v2 differences that affect routing payloads:

• customer (v1) becomes customers (v2).
• targetAssignment is available in v2.
• Omitted Genesys chatMode defaults differ (genesys-cloud in v1, genesys-web-messaging in v2).

chatMode defaults

chatMode controls chat runtime/channel semantics for the interaction.

If interaction.routing.properties.chatMode is omitted:

• v2 + Genesys defaults to genesys-web-messaging (see v2 schedule).
• v1 + Genesys defaults to genesys-cloud (deprecated v1 endpoint behavior; see v1 schedule).
• Talkdesk defaults to talkdesk-digital-connect (applies in v2 and in deprecated v1 behavior).

If chatMode is provided explicitly, that value is preserved.

Request shape

The interaction object lets the caller influence where and how the interaction is routed. It has two parts:

• interaction.routing: platform selection and routing inputs.
• interaction.customFields: key/value data propagated for downstream flow logic.

How each part is applied:

• interaction.routing.type chooses the routing path (GENESYS_CLOUD_FLOW, GENESYS_CLOUD_QUEUE, TALKDESK_DIGITAL_CONNECT).
  • If omitted, the backend selects a default by application type.
• interaction.routing.properties carries provider-specific inputs (for example queueName, deploymentId, touchpointId, chatMode).
  • Request values are used when valid; server-owned values are injected/overridden where required (for example pcEnvironment).
• interaction.customFields is passed through as context payload for downstream logic.
  • It does not choose the routing type, but it is available in flow/studio logic after scheduling.

Practical routing examples:

• Queue via API: set interaction.routing.type=GENESYS_CLOUD_QUEUE and provide interaction.routing.properties.queueName (or in v2 use targetAssignment.type=QUEUE to drive queue selection).
• Flow via API: set interaction.routing.type=GENESYS_CLOUD_FLOW (or omit type for Genesys defaults).
• Choose explicit runtime channel behavior with interaction.routing.properties.chatMode when needed.

{
  "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"
    }
  }
}

Routing types

interaction.routing.type supports:

• GENESYS_CLOUD_FLOW
• GENESYS_CLOUD_QUEUE
• TALKDESK_DIGITAL_CONNECT

interaction.routing.properties contains type-specific inputs.

GENESYS_CLOUD_FLOW

Use GENESYS_CLOUD_FLOW to route to a Genesys inbound chat flow.

• Default for Genesys apps when routing.type is omitted.
• Required after normalization: deploymentId, pcEnvironment, chatMode.
• deploymentId uses request value when provided, otherwise app config value.
• pcEnvironment is always sourced from app config and overrides any client value.

GENESYS_CLOUD_QUEUE

Use GENESYS_CLOUD_QUEUE to route directly to a Genesys queue.

• Required after normalization: deploymentId, pcEnvironment, queueName, chatMode.
• deploymentId uses request value when provided, otherwise app config value.
• pcEnvironment is always sourced from app config and overrides any client value.
• queueName must resolve to a non-empty value.

TALKDESK_DIGITAL_CONNECT

Use TALKDESK_DIGITAL_CONNECT to route through Talkdesk Digital Connect.

• Default for Talkdesk apps when routing.type is omitted.
• Required after normalization: touchpointId, chatMode.
• touchpointId uses request value when provided, otherwise Talkdesk app config value.

chatMode values

chatMode can be provided with any routing type and must resolve to a non-empty value.

Common examples:

• Genesys: genesys-web-messaging, genesys-cloud (omitted defaults depend on endpoint version)
• Talkdesk: talkdesk-digital-connect

For widget-side options, see interaction widget configuration.

genesys-web-chat (Genesys ACD Web Chat) should be treated as retired by Genesys Cloud:

• Deprecation: Removal of ACD Web Chat

Server normalization and validation

When processing interaction.routing, the server applies normalization rules:

• If routing.type is omitted, server selects default by app type:
  • Genesys app -> GENESYS_CLOUD_FLOW
  • Talkdesk app -> TALKDESK_DIGITAL_CONNECT
• If routing.type is provided but incompatible with the app type, server falls back to the app-type default.
• Server-owned properties are injected/overridden:
  • pcEnvironment from Genesys app config
  • deploymentId from Genesys app config when omitted
  • touchpointId from Talkdesk app config when omitted
• Routing keys are normalized case-insensitively for known routing properties.
• If required properties are still missing after defaults/normalization, the request is rejected.

Target assignment (v2)

targetAssignment is available in v2 and can bind the appointment to an agent or queue (see v2 schedule).

Shape:

{ "type": "AGENT" | "QUEUE", "id": "<identifier>" }

Behavior:

• Genesys + type=QUEUE:
  • Requires queue routing (GENESYS_CLOUD_QUEUE).
  • Assignment sets routing.properties.queueName.
  • If request also provides queueName, request value wins.
• Genesys + type=AGENT:
  • Requires non-queue routing.
  • Sets routing.properties.agentId.
• Talkdesk + type=AGENT:
  • Supported.
  • Server derives routing.properties.talkdeskAgentId from assigned agent profile.
• Talkdesk + type=QUEUE:
  • Not supported.

Additional Talkdesk defaulting for schedule requests:

• In POST /api/v2/appointments, if targetAssignment is omitted and caller is an agent (non-client-service), backend auto-assigns the authenticated agent.
• This automatic assignment does not apply to customer scheduling (POST /api/v2/appointments/basic).

Custom fields

interaction.customFields is a key/value map passed into contact-center flows.

Genesys

In Genesys Architect, custom fields are available as participant data via context.<key>.

Example:

• Request key: field1
• Architect usage: context.field1

Talkdesk

Talkdesk Studio may receive additional incoming variables beyond interaction.customFields (for example standard Auvious arguments and other metadata fields). For the full Studio variable scope, see Talkdesk appointment setup.

In Talkdesk Studio incoming message variables, key names cannot contain dots (.). Use underscores (_).

• Not allowed: my.custom.property
• Allowed: my_custom_property

Examples

v2: queue routing with explicit chatMode

Endpoint: Schedule Appointment (v2)

{
  "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-cloud"
      }
    },
    "customFields": {
      "cf1": "cf_value1",
      "cf2": "cf_value2"
    }
  },
  "customers": [
    {
      "username": "bDillon_",
      "name": {
        "firstName": "Bob",
        "lastName": "Dillon"
      },
      "metadata": {
        "refNo": "CS-9838"
      }
    }
  ]
}

v2: flow routing with omitted chatMode

Endpoint: Schedule Appointment (v2)

{
  "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 with agent assignment

Endpoint: Schedule Appointment (v2)

{
  "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"
      }
    }
  ]
}

v1 (Deprecated reference): queue routing with explicit chatMode

Endpoint: Schedule Appointment (v1, deprecated)

{
  "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-cloud"
      }
    },
    "customFields": {
      "cf1": "cf_value1",
      "cf2": "cf_value2"
    }
  },
  "customer": {
    "username": "bDillon_",
    "name": {
      "firstName": "Bob",
      "lastName": "Dillon"
    },
    "metadata": {
      "refNo": "CS-9838"
    }
  }
}

v1 (Deprecated reference): flow routing with omitted chatMode

Endpoint: Schedule Appointment (v1, deprecated)

{
  "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"
    }
  }
}