Conversations models use Memory v1's 8-value channel enum, so a VIDEO address fails to parse and VOICE is accepted on send

Open
#133 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 5 days

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
python, typescript
Domain
api

Research direction

Start with src/tac/models/conversation.py and the referenced TypeScript schemas in packages/core/src/types/conversation.ts; compare their channel types with the canonical Conversations enums cited in the issue. First resolve whether the documented EMAIL address is supported or the spec prose is stale. Done when receive/address and send channels match the confirmed definitions and both SDKs accept valid responses while rejecting invalid send channels.

Written by the indexing model from the issue text.

Description

What differs

Both SDKs use a single 8-value channel union for every channel field in the Conversations v2 models. The canonical definition has two channel enums for Conversations, with six and four values, and neither is the union the SDKs use.

Verified against main today (2026-10-08): Python at 2c24bd988c, TypeScript at c34450aa8c. All line citations are for navigation only.

source values
SDK union (both languages) VOICE SMS RCS EMAIL WHATSAPP CHAT API SYSTEM
conversations.v2.channel (receive/address) VOICE SMS RCS WHATSAPP CHAT VIDEO
conversations.v2.send_channel (send) SMS RCS WHATSAPP CHAT

The canonical enums are in twilio/twilio-oai spec/yaml/twilio_conversations_v2.yaml at 141f1201b5, :1997-2005 and :2007-2015.

The SDK union appears to have been taken from Memory v1, not Conversations: spec/yaml/twilio_memory_v1.yaml:3450-3461 declares Participant.channel as exactly those eight values, in exactly that order. That is the mechanism rather than a guess — the order matches member for member.

Sites:

  • Python src/tac/models/conversation.py:83 (ParticipantAddress), :270 (CommunicationParticipant), :445 (ActionParticipantRef)
  • TypeScript packages/core/src/types/conversation.ts:9-18 (ParticipantAddressTypeSchema), applied at :25, :39, :124 (ActionParticipantRefSchema) and :302 (ConversationAddressSchema)

Three consequences, one of which breaks reads

  1. VIDEO is rejected on the read path. conversations.v2.channel includes VIDEO; the SDK union does not. A participant carrying a VIDEO address makes ParticipantResponse(**response.json()) raise ValidationError in Python and makes ListParticipantsResponseSchema.parse(data) throw in TypeScript — so list_participants / listParticipants fails on a response the API is entitled to send. This is the sharpest one: a caller cannot read the conversation at all, and no caller mistake is involved.

  2. EMAIL, API and SYSTEM are accepted client-side where the Conversations definition does not declare them, so a caller who sets one gets a service-side 400 instead of a type error at the point of the mistake.

  3. The send path accepts receive-only channels. ActionParticipantRef (conversation.py:445, conversation.ts:124) is the from/to of a SEND_MESSAGE action, where the definition uses send_channel — four values, with the note "VOICE is receive-only and not supported for send operations." The SDKs permit VOICE, plus the three undeclared values.

What the models should declare

Two distinct types rather than one, matching the two canonical enums:

  • an address/receive channel — VOICE SMS RCS WHATSAPP CHAT VIDEO — for ParticipantAddress, CommunicationParticipant, ConversationAddress
  • a send channel — SMS RCS WHATSAPP CHAT — for ActionParticipantRef

If Memory v1's eight-value enum is needed for Memory models, keeping it under its own name would stop it being reused where Conversations' narrower enums apply.

One thing to confirm on your side

The canonical definition is not entirely self-consistent here, so please check this rather than taking the table above as settled. conversations.v2.participant's addresses description still documents an EMAIL address format — "- EMAIL: Email address (such as "[email protected]")", twilio_conversations_v2.yaml:462, and at four further sites — while the channel enum it points at has no EMAIL. So either the enum is missing a value or the prose is stale, and we cannot tell which from outside. If EMAIL is genuinely supported, the fix is in the definition and only VIDEO and the send/receive split apply to the SDKs.

Context, and no urgency implied

Found while building an OpenAPI-driven client generator against the canonical twilio-oai specs and comparing its output with the hand-written SDKs. Filed here rather than in the TypeScript repo because the two track each other and Python looks like the source (your twilio-agent-connect-typescript HEAD is "Synced from Python"); the TypeScript sites are listed above so both can move together. We are not blocked and nothing here needs a response on any timeline.

Dominant language
Python
Stars
17
Forks
11
Avg merge
5d 19h
Merged PRs (30d)
6

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from twilio/twilio-agent-connect-python

All issues in twilio/twilio-agent-connect-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.