chat-core/dev.hatang.chat.core.http/WidgetApi

WidgetApi

open class WidgetApi(baseUrl: String, val siteId: String, val appKey: String, val userAgent: String, client: OkHttpClient? = null, val timeout: Duration = 20.seconds)

The visitor REST API (/widget/v1/sites/{siteId}/…) over OkHttp. Every call sends the app key and the user agent; token calls add x-visitor-token. Failures throw HatangException: gateway errors ({statusCode, name, message}) keep their name as HatangException.code and the HTTP status; transport failures are network_error. Open so tests can script it.

Constructors

WidgetApi

constructor(baseUrl: String, siteId: String, appKey: String, userAgent: String, client: OkHttpClient? = null, timeout: Duration = 20.seconds)

Properties

appKey

val appKey: String

The site app key (hak_…).

siteId

val siteId: String

The site.

timeout

val timeout: Duration

Per-request timeout (whole call).

userAgent

val userAgent: String

User-Agent sent on every call.

Functions

bootstrap

open suspend fun bootstrap(app: AppContext, token: String? = null, screen: ScreenInfo? = null, locale: String? = null, campaign: Map<String, String>? = null): BootstrapResponse

First call: config, a visitor token (new or existing) and the current conversation.

open fun close()

Releases the HTTP client when this API created it.

deleteDevice

open suspend fun deleteDevice(token: String, pushToken: String): Boolean

Removes a push token. A gateway without the endpoint (404) returns false.

lead

open suspend fun lead(token: String? = null, name: String? = null, phone: String? = null, email: String? = null, message: String? = null, source: String? = null, fields: Map<String, String>? = null): LeadResult

Lead capture (works without a token).

listConversations

open suspend fun listConversations(token: String, status: String = "all", limit: Int? = null, after: String? = null): ConversationPage

The visitor's conversations, newest activity first, resolved ones included.

messages

open suspend fun messages(token: String, conversationId: String, afterSeq: Int? = null, beforeSeq: Int? = null, limit: Int? = null): MessagesPage

Timeline items of one conversation: after afterSeq (forward) or before beforeSeq (older history, the newest limit before it; afterSeq is then ignored).

offlineMessage

open suspend fun offlineMessage(token: String, message: String, name: String? = null, email: String? = null): OfflineMessageResult

Offline / pre-chat form.

postPurchase

open suspend fun postPurchase(token: String, platform: String, storeProductId: String, transactionId: String?, conversationId: String?, amount: Double?, currency: String?, purchaseToken: String? = null, productType: String? = null, kind: String? = null, signedTransaction: String? = null): Boolean

Reports a finished store purchase: verified with the store when purchaseToken (Android) or signedTransaction (iOS) is given, plus an internal note for the team. A gateway without the endpoint (404) returns false.

putDevice

open suspend fun putDevice(token: String, device: DeviceRegistration): Boolean

Registers (or moves) a push token for this visitor. A gateway without the endpoint (404) returns false.

reset

open suspend fun reset(token: String, installId: String? = null): ResetResult

Forget this visitor; the old token stops working.

restoreSession

open suspend fun restoreSession(linkToken: String): RestoreResult

Swap a magic-link token for the visitor's session.

sendMessage

open suspend fun sendMessage(token: String, conversationId: String, clientId: String, content: String, attachments: List<String>? = null): SendResult

HTTP fallback for message.send.

upload

open suspend fun upload(token: String, bytes: ByteArray, filename: String, contentType: String, onProgress: UploadProgress? = null): Attachment

Uploads a file (multipart field file); the returned id goes into message.send.attachments. onProgress is called from an OkHttp thread as the body goes out.

url

fun url(path: String, query: Map<String, String>? = null): HttpUrl

Builds the URL for path (/bootstrap) under the site.