Documentation

Everything you need to integrate OnePaste Chat into your application.

Quick Start

Add the OnePaste Chat widget to your website with just two lines of code. Include the script tag and place the chatbox component wherever you want it to appear.

HTML

<script src="https://onepastechat.com/api/widget"></script>

<opc-chatbox
  public_key="<YOUR_PUBLIC_KEY>"
  user_id="jacob_123"
  user_nickname="Jacob"
  user_img="https://api.dicebear.com/7.x/avataaars/svg?seed=jacob"
  room_name="jacob-and-emma-banter"
></opc-chatbox>

Replace <YOUR_PUBLIC_KEY> with your project's public key from the dashboard. Try it live in the playground.

Widget Reference

The <opc-chatbox> component accepts the following attributes to configure its behavior and appearance.

Attribute	Type	Required	Description
`public_key`	string	Yes	Your project's public API key from the dashboard
`user_id`	string	Yes	Unique identifier for the user in your system. Can be any string.
`user_nickname`	string	Yes	Display name shown alongside the user's messages
`user_img`	string	Yes	URL to the user's avatar image
`room_name`	string	Yes	Name of the chat room. Users with the same room_name will chat together.
`label`	string	No	Custom label displayed in the chat header. Default: "Onepaste Chatbox"

Tip

The room_name and user_id values can be anything you want. Use descriptive names like "support-chat-user123" or playful ones like "jacob-and-emma-banter" - it's up to you!

API Reference

POST /api/v1/chatbox/joinroom

Auto-Join Enabled?

If you've enabled Auto-Join in your project dashboard, you don't need to call this API. The widget handles room creation and user registration automatically. This API is only needed for server-side control or advanced use cases.

Manually creates or joins a chat room and registers a user from your backend. Use this when you need server-side control over room creation, want to pre-register users before they open the widget, or have Auto-Join disabled. This endpoint is idempotent — calling it multiple times with the same parameters is safe.

Request Body

Field	Type	Required	Description
`private_key`	string	Yes	Your project's private API key (keep this secret!)
`room_name`	string	Yes	Name of the room to create or join
`user_id`	string	Yes	Unique identifier for the user
`user_nickname`	string	Yes	Display name for the user
`user_img`	string	Yes	URL to user's avatar image

Example Request

JavaScript

fetch('https://onepastechat.com/api/v1/chatbox/joinroom', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    private_key: '<YOUR_PRIVATE_KEY>',
    room_name: 'jacob-and-emma-banter',
    user_id: 'jacob_123',
    user_nickname: 'Jacob',
    user_img: 'https://api.dicebear.com/7.x/avataaars/svg?seed=jacob'
  })
})

Success Response (200)

JSON

{
  "success": true,
  "chatRoom": {
    "id": 123,
    "room_name": "jacob-and-emma-banter",
    "project_id": 1
  },
  "chatter": {
    "id": 456,
    "client_user_id": "jacob_123",
    "user_nickname": "Jacob",
    "user_img": "https://api.dicebear.com/7.x/avataaars/svg?seed=jacob"
  }
}

Error Response

JSON

{
  "error": "Missing required fields: private_key, room_name, user_id, user_nickname, user_img",
  "status": 400,
  "incidentId": "550e8400-e29b-41d4-a716-446655440000"
}

Security Warning

Never expose your private_key in client-side code. Only call this endpoint from your backend server. Use the public_key for the widget on the frontend.