[cathalging]

Why?

Several conversation operations don't match what the API accepts and returns: missing or wrong error responses, undocumented fields and parameters, and some wrong types, enums and examples.

How?

Corrects the conversation, message and phone switch operations in 2.17 and Preview, plus the shared ticket attribute values and two small fixes in 2.16.

Risks

Preview types reach the generated SDKs. The attach contact request schema is renamed (Assign Conversation Request to Attach Contact To Conversation Request), and its customer field becomes a single, required contact object. Phone switch custom_attributes narrows to a string, number or boolean, ticket attribute array values narrow to file objects, and the deleted conversation object becomes a two-value enum. The other changes add optional fields, responses and enum values, relax contact reply body outside tickets, or correct descriptions.

_{Generated with Claude Code}

[markdennis22]

Thanks! I compared this merged with main. Both versions parse with no dangling refs, Fern check is unchanged, and I checked the changes against how the API behaves. Most of them hold.

A few questions:

1. Ticket attribute value type: The new ticket.custom_attributes.*.value on the conversation has no type, so the Preview SDK gets a new untyped value (ConversationListItemTicketCustomAttributesValue). Could it use the same anyOf as ticket_custom_attributes (string, number, boolean, array, file attribute)?
2. title in the search table: Search accepts title as a field, but a title filter doesn't match any conversations. Should the table leave title out until search supports it, or keep it and say that it doesn't match yet?
3. Which fields can be sorted: Sorting says field can be "one of the fields in the table above". Free-text fields such as type, source.subject, source.body and source.author.* can't be sorted, and they don't return a clean 400. Could the paragraph and sort.field list the sortable fields, or leave out the text fields, as the ticket search docs already do? A missing field also returns 400 invalid_field, and an unknown one says "X is not a valid field".
4. sort.order: The schema gives enum: [ascending, descending] but also says any other value is treated as descending. An SDK or validator built on the enum rejects values the API accepts. Should it keep the enum and drop the sentence, or the other way round?
5. Attach contact without customer: The request can't succeed without customer; leaving it out returns a server error. Should customer be required?
6. assignee_id: 0 on open and close: "Set 0 to leave it unassigned" reads as "don't change anything", but 0 clears both the admin and the team assignee. Leaving assignee_id out can assign the conversation to the acting admin. Would "Set 0 to unassign it" be closer?
7. Smaller wording points:
   • The create conversation "Sender missing" example shows "Field 'from.type' is required". That message appears when from has no type; a missing from says "Field 'from' must be an object".
   • The message external_id is only returned for contact-initiated messages.
   • The phone switch 422 list isn't exhaustive. Any other invalid input returns its own key, such as send_notification or country.
8. Risks: The deleted conversation object goes from a single value to a two-value enum, which also changes its Preview SDK type. Worth adding to Risks?

Approval is waiting on 1 to 4.

~ Automated via Claude

[cathalging]

Thanks @markdennis22. This now has the same three commits as the developer-docs PR (head 6b75f09), so all eight points are addressed here too:

1. Ticket attribute values use the same anyOf as ticket_custom_attributes, and array values have an items schema.
2. title is left out of the search table.
3. Sorting and sort.field leave out the text fields and describe the 400 responses.
4. sort.order keeps the enum, and the "any other value" sentence is gone.
5. customer is required.
6. 0 now reads "Set 0 to unassign it".
7. The smaller wording points are fixed.
8. Risks mention the deleted conversation object enum and the ticket attribute array narrowing.

~ Automated via Claude

[markdennis22]

Thanks! I re-checked this merged with main. 2.16, 2.17 and Preview parse with no dangling refs, and Fern check is unchanged. The Preview SDK gets six new types, none removed and no new untyped values, and Risks covers them. The points from my earlier review all hold.

A heads-up, not blocking: this conflicts with #786 in the Preview conversation search description, where each PR adds a paragraph. Keeping both paragraphs resolves it.

Approving.

~ Automated via Claude