Tips

Tipping lets users in your chat send monetary tips to each other. A viewer can tip another user or a streamer directly from the chat interface — the receiver gets a notification and can accept, return, or block the tip.

Use tipping to increase engagement and monetization in your chat rooms: live streams, sports events, community discussions, and other interactive formats.

How It Works

Sending a Tip

A user opens the tip form by tapping the tip button next to a message or through the Chat Actions menu (on streams).

The tip form shows the recipient's name, an amount input with a currency selector, and the sender's available balance. The sender can also mark a tip as private — private tips won't appear in the public chat.

After sending, the sender sees a confirmation screen. The tip remains pending until the recipient responds. If the recipient does not respond within the configured timeout, the tip is automatically declined.

If the tip cannot be processed, the sender sees an error notification.

Receiving a Tip

When someone sends a tip, the receiver gets a banner notification in the chat with a countdown timer showing how long they have to respond.

Tapping "Review tip" opens the tip details. The receiver has three options:

• Accept — the tip is processed and funds are transferred to the receiver.
• Return Tip — the tip is declined.
• Block & Return — the tip is declined and the sender is blocked. The users won't see each other in chat.

If the receiver chooses "Block & Return", they select a reason: "Amount too large", "Unwanted attention", "Sent by mistake", or "Other".

After declining, the sender sees a notification.

After blocking, a confirmation is shown.

Sending a Tip on a Stream

On stream pages, tipping is available through the Chat Actions menu. The user taps the menu icon and selects "Send Tip". The tip is sent to the streamer (room owner).

Admin Panel Setup (Required)

Before API integration, you must enable OAuth and tipping in Chat Admin.

OAuth is mandatory for tipping security. If OAuth is disabled, tipping will be automatically unavailable.

1. Open Functional settings.
2. Enable Oauth.
3. Fill in Oauth url.
4. Click Save.
5. On the same page, enable Enable tipping.
6. Click Save again.
7. Open Tips (this section appears after tipping is enabled).

Configure Tips section

1. In General, configure limits, room restrictions, accept timeout, cooldowns, role restrictions, and anti-abuse rules.
2. In Claim settings, set:
   • Tips claim URL
   • Tips claim bearer
3. In Currency and fees, add currencies, enable active ones, and configure payment fee.
4. Click Save.

Mapping to integration fields

These values are used in the Process payment and Get payment status endpoints.

Required headers for all API endpoints

Endpoints you must implement

These endpoints are called by the Tipping Service. Your backend must implement them.

Validate user

Called on every tip creation — twice: once for receiver, once for sender. Validates that users exist in the room and are allowed to tip.

GET Endpoint: ${BACKEND_URL}/internal/talker/tip

Request query parameters

CURL example (how the Tipping Service calls your backend):

curl --location '${BACKEND_URL}/internal/talker/tip?userId=42&externalRoomId=room-123&project=my-project' \
--header 'Authorization: Bearer ${INTERNAL_BEARER_TOKEN}'

Expected response:

{
  "externalUserId": "partner-user-abc123",
  "userName": "john_doe",
  "roles": "SPEAKER,MODERATOR",
  "isBanned": false,
  "reportCount": 0,
  "autoAcceptTips": false
}

Response fields

Validation checks applied:

Process payment

Called when a tip is accepted. partnerUrl and partnerToken are configured per project via admin settings.

POST Endpoint: ${partnerUrl}/payment

Request payload

CURL example (how the Tipping Service calls your payment partner):

curl --location -X POST "${partnerUrl}/payment" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${partnerToken}" \
  --data '{
    "senderId": "partner-user-abc123",
    "receiverId": "partner-user-xyz789",
    "amount": 50.00,
    "currency": "USD",
    "internalTransactionId": 1
  }'

Expected response:

{
  "transactionId": "ext-txn-456",
  "status": "SUCCESS",
  "processedAt": "2025-01-15T12:05:00.000Z"
}

Response fields

Get payment status

The Tipping Service periodically polls this endpoint for tips in PROCESSING state.

GET Endpoint: ${partnerUrl}/payment/status/${transactionId}

CURL example:

curl --location "${partnerUrl}/payment/status/ext-txn-456" \
  --header "Authorization: Bearer ${partnerToken}"

Expected response:

{
  "status": "SUCCESS"
}

Allowed status values (case-insensitive):