On /docs/server-sdks/reference/python/agents/ai-chat-client/create-conversation, the conversation_id parameter is described as "The conversation id. You choose it, and it is scoped to your project," and nothing more.
The service silently strips any character outside a-zA-Z0-9_-.: on arrival, with no error at any layer. An id like root~2 is stored as root2, which is a different and perfectly valid-looking id, so everything filed under the id the caller asked for becomes unreachable and nothing reports that the id changed.
The SDK treats this as serious enough to warn about at runtime: _warn_if_id_will_be_altered in signalwire/ai_chat/client.py logs conversation_id_will_be_sanitized with the requested id, the id it will be stored as, and the characters removed.
Its docstring also carries the guidance that belongs on the page. Two of the three risky characters come from the SDK itself: _ and - both appear in secrets.token_urlsafe output, which is what ChatGateway.mint_handle uses to generate ids, so a suffix built from either cannot be told apart from the id it was appended to. : is the gateway's own handle delimiter. That leaves . as the safe separator for composing ids.
What to do
Document on the create_conversation page:
- The permitted character set.
- That stripping is silent, and what the failure looks like (data filed under an id that no longer resolves).
- That
. is the separator to use when composing an id from a parent id.
On
/docs/server-sdks/reference/python/agents/ai-chat-client/create-conversation, theconversation_idparameter is described as "The conversation id. You choose it, and it is scoped to your project," and nothing more.The service silently strips any character outside
a-zA-Z0-9_-.:on arrival, with no error at any layer. An id likeroot~2is stored asroot2, which is a different and perfectly valid-looking id, so everything filed under the id the caller asked for becomes unreachable and nothing reports that the id changed.The SDK treats this as serious enough to warn about at runtime:
_warn_if_id_will_be_alteredinsignalwire/ai_chat/client.pylogsconversation_id_will_be_sanitizedwith the requested id, the id it will be stored as, and the characters removed.Its docstring also carries the guidance that belongs on the page. Two of the three risky characters come from the SDK itself:
_and-both appear insecrets.token_urlsafeoutput, which is whatChatGateway.mint_handleuses to generate ids, so a suffix built from either cannot be told apart from the id it was appended to.:is the gateway's own handle delimiter. That leaves.as the safe separator for composing ids.What to do
Document on the
create_conversationpage:.is the separator to use when composing an id from a parent id.