[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.

Outbound conversation start split per channel

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.0.2 (patch — the removed endpoint has no known users, so this does not warrant a major bump); 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.0.2 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

Release workflow fix

.github/workflows/release.yml set up JDK 11 while the poms compile with source/target 17, so mvn deploy would have failed at compilation with invalid target release: 17 on the first tag push. Now 17, matching CI.

The READMEs also claimed "Java 11 or higher" in four places, wrong since the move to 17: class files are version 61, so an 11 runtime fails with UnsupportedClassVersionError after resolving the dependency rather than at build time. Now 17.

Verified with mvn verify (BUILD SUCCESS, 15 tests) and mvn -P release package -DskipTests -Dgpg.skip=true (BUILD SUCCESS).

[gmtuca]

Merge activity

• Aug 4, 3:46 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Aug 4, 3:46 PM UTC: @gmtuca merged this pull request with Graphite.