klink-developers-logo

Schemas

Shared data models referenced by the API endpoints. The full machine-readable definition is available as openapi.yaml.

string<uuid>

RequestId

Unique ID for this request, useful when contacting support.

object

IdentityVerificationStatus

  • requestIdstring<uuid>required

    Unique ID for this request, useful when contacting support.

  • secretConfiguredbooleanrequired

    Whether an identity secret exists for this channel.

  • enforceIdentityVerificationbooleanrequired

    When true, unverified identities are treated as anonymous guests.

  • requireIdentityTokenbooleanrequired

    When true, only expiring userTokens are accepted, and the legacy userHash is refused.

object

IdentityVerificationUpdate

Send at least one field.

  • enforcebooleanoptional

    Require every logged-in user to be verified.

  • requireTokenbooleanoptional

    Accept only expiring userTokens, and refuse the legacy userHash.

object

IdentityVerificationSettings

  • requestIdstring<uuid>required

    Unique ID for this request, useful when contacting support.

  • enforceIdentityVerificationbooleanrequired
  • requireIdentityTokenbooleanrequired
object

IdentitySecret

  • requestIdstring<uuid>required

    Unique ID for this request, useful when contacting support.

  • secretstringrequired

    64 hex characters. Shown only once. Keep it on your server.

object

UserTokenClaims

Not an API response. This describes the token your server creates and passes to the widget as authUser.userToken, or to the hosted chat page as ?userToken=.

Sign it as a JWT with algorithm HS256, using the channel secret. Only HS256 is accepted. Create a fresh token each time the chat opens.

  • substringrequired

    Your user's unique, stable ID. It must never change for that user. To identify users by email, set sub to the email and also include email.

    Example:cust_9931

  • expinteger<int64>required

    Expiry time in unix seconds. Recommended: 10 minutes from now. Tokens valid for more than 24 hours are rejected. Up to 60 seconds of clock difference is tolerated.

    Example:1790661969

  • iatinteger<int64>optional

    Issue time in unix seconds. Recommended.

    Example:1790661369

  • nbfinteger<int64>optional

    Optional "not before" time in unix seconds.

  • namestringoptional

    Display name shown to agents. It's signed, so visitors can't change it.

    Example:Jane Doe

  • emailstring<email>optional

    Email shown to agents. Signed.

  • phonestringoptional

    Phone number shown to agents. Signed.

    Example:+95912345678

object

Error

  • messagestringrequired
  • errorstringoptional
  • statusCodeintegerrequired
object

CxLogTranscriptResponse

  • requestIdstring<uuid>required
  • dataCxLogTranscriptrequired
    Child attributes
    • cxLogIdstring<uuid>required
    • caseIdinteger<int64>required
    • roomIdstring<uuid>required

      The chat room the case belongs to.

    • channelstring | nullrequired

      Example:line

    • transcriptstringrequired

      Newline-separated transcript lines, oldest first.

object

CxLogTranscript

  • cxLogIdstring<uuid>required
  • caseIdinteger<int64>required
  • roomIdstring<uuid>required

    The chat room the case belongs to.

  • channelstring | nullrequired

    Example:line

  • transcriptstringrequired

    Newline-separated transcript lines, oldest first.

object

ValidationError

  • messagearray[string]required
  • errorstringoptional
  • statusCodeintegerrequired