ParticipantResponse.name is required where the API definition marks it nullable, so a nameless participant fails to parse

Open Beginner friendly
#134 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 5 days

@TheeCoderAhmed is already working on this.

Since Oct 29, 2026.

  • #147 by @TheeCoderAhmed — open

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
86/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
api

Research direction

Read src/tac/models/conversation.py and the ParticipantResponse declaration around lines 237–243; compare its name field with the nullable, optional definition cited in the issue. Check the participant construction paths in src/tac/context/conversation.py and run the relevant model or context tests. Done when responses with name missing or null parse successfully while the other required fields remain required.

Written by the indexing model from the issue text.

Description

What differs

ParticipantResponse.name is a required, non-nullable str, where the canonical definition marks the field nullable and does not require it. A participant with no display name therefore raises ValidationError client-side on a response the API is entitled to send.

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

# src/tac/models/conversation.py:237-243
class ParticipantResponse(BaseModel):
    id: str = Field(..., description="Participant ID")
    conversation_id: str = Field(..., alias="conversationId", description="Conversation ID")
    account_id: str = Field(..., alias="accountId", description="Account ID")
    name: str = Field(..., description="Participant display name")

What the definition declares

twilio/twilio-oai spec/yaml/twilio_conversations_v2.yaml, schema conversations.v2.participant at 141f1201b5 (:422-445):

  • required: is id, conversationId, accountId — name is not in it
  • name is type: string with nullable: true

The other three required fields match the model exactly, so name is the only divergence in this class.

Consequence

create_participant, update_participant and list_participants all construct ParticipantResponse(**...) (src/tac/context/conversation.py:140, :204, :228). Any participant the service returns without a name — or with "name": null, which nullable: true permits — makes all three raise, so the caller cannot read a conversation's participants rather than reading them with name=None.

What the model should declare

name: str | None = Field(None, description="Participant display name"), matching the treatment profile_id, created_at and updated_at already get in the same class.

The TypeScript port has a milder instance of the same thing

Not a separate report, since the two SDKs track each other — twilio/twilio-agent-connect-typescript at c34450aa8c, packages/core/src/types/conversation.ts:316:

export const ConversationParticipantSchema = z.object({
  ...
  name: z.string().optional(),      // :316 — accepts missing, rejects null

.optional() admits undefined but not null, so an explicit "name": null fails ListParticipantsResponseSchema.parse. The same file already uses the right shape twice for exactly this reason, with the reason in the comment — :281 name: z.string().nullish(), // API returns null when not set and :304 channelId: z.string().nullish(), // API returns null when not set. .nullish() at :316 would make it consistent.

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. We are not blocked — 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.