[api-sync 2026-07-31] gradientlabs-java: split outbound conversation start into chat/email/phone

[gmtuca]

Syncs the Java SDK to the public API change that removed POST /outbound/conversations and replaced it with three channel-specific endpoints.

Breaking change

GradientLabsClient.startOutboundConversation(...) and StartOutboundConversationRequest (including its nested CustomerSource / SupportPlatform constant classes) have been removed. There is no deprecation window — the underlying endpoint no longer exists.

New methods, each with its own request type:

Old	New	Endpoint
startOutboundConversation(...) with channel = "web"	startOutboundChatConversation(StartOutboundChatConversationRequest)	POST /outbound/conversations/chat
startOutboundConversation(...) with channel = "email"	startOutboundEmailConversation(StartOutboundEmailConversationRequest)	POST /outbound/conversations/email
startOutboundConversation(...) with channel = "voice"	startOutboundPhoneConversation(StartOutboundPhoneConversationRequest)	POST /outbound/conversations/phone

All three return the existing StartOutboundConversationResponse (conversation_id).

Migration

Old field	New
channel	Pick the matching method: voice → phone, email → email, web → chat. Phone has no channel or support-platform field at all.
customerSource	No replacement. customerId is now always your own customer ID — the one echoed back in tool and webhook payloads.
third-party platform IDs	customerSupportPlatformIdentifiers (the existing CustomerSupportPlatformIdentifier type already used by startConversation), keyed by platform. Zendesk requires subtype zendesk_support_user; Salesforce requires salesforce_contact_id.
supportPlatform	Now required on chat and email — the API no longer auto-selects the highest-priority connected platform. Valid values: chat intercom, public-api; email intercom, zendesk, salesforce, public-api (exposed as constants on each request class).
subject / body	Email only, and required together — setting just one now throws IllegalArgumentException at build time, mirroring server-side validation. Chat takes body alone; phone takes neither.
—	Phone adds required toPhoneNumber and fromPhoneNumber (E.164; the from-number must already be provisioned for your company).

Version

1.0.1-SNAPSHOT → 1.1.0 (minor, by request — note this is still a breaking change for callers, so the version alone will not signal it; non--SNAPSHOT so it is releasable). Bumped in the root pom, both module poms, the example app's dependency pin, and the install snippets in both READMEs.

The client jar now stamps Implementation-Version into its manifest, so the User-Agent reports Gradient-Labs-Java/1.1.0 instead of the dev fallback it has been sending since 1.0.0.

Verification

mvn verify from the repo root: BUILD SUCCESS, Tests run: 15, Failures: 0, Errors: 0, Skipped: 0. Eight new tests cover serialization of all three payloads, omission of unset optionals, the required-field checks, and the email subject/body pairing rule.

🤖 Generated with Claude Code