Widget Setup

This guide explains how to create and configure a widget in the Traise platform.

Prerequisites

Before creating a widget, ensure you have:

• An active Traise account with widget access enabled on your plan
• At least one phone number provisioned in your account
• A business profile set up (required for calls and messaging)

Creating a Widget

1. Navigate to Settings > Widgets in the Traise app
2. Click the Create Widget button
3. Fill in the required configuration options (see below)
4. Click Create
5. Important: Copy your API key when displayed - it will only be shown once

Configuration Options

Basic Information

Setting	Required	Description
Widget Name	Yes	A descriptive name for your widget (e.g., "Support Widget", "Sales Chat")
Profile	Yes	The business profile to associate with this widget. This determines the caller ID and business identity.
Phone Number	Yes	The phone number used for calls and SMS. Only unassigned numbers are available.
Timezone	Yes	The timezone for the widget (affects call logs, message timestamps, etc.)

Widget Settings

Setting	Default	Description
Allow External Numbers	Enabled	When enabled, users can dial any phone number using the dialpad. When disabled, calls can only be initiated via your application's API.
Sync Contacts	Enabled	When enabled, the widget can access and create contacts in your Traise account. Disable this if you want to manage contacts entirely through your own system.

Support Team (Optional)

Add team members who should be available for widget users to contact directly. Selected team members will appear in the widget's peer calling feature, allowing users to call specific support agents.

Webhooks (Optional)

Configure webhook URLs to receive real-time notifications about widget activity:

Webhook	Description
Call Webhook URL	Receives notifications for call events (started, ended, missed, etc.)
SMS Webhook URL	Receives notifications for incoming and outgoing messages

Webhook payloads are signed using your widget's signing secret for verification.

Allowed Domains

You must specify at least one domain where the widget is allowed to run. This is a security measure to prevent unauthorized use of your widget.

Examples:

• https://yourapp.com
• https://www.yourapp.com
• https://staging.yourapp.com

For local development, you can add:

• http://localhost:3000
• http://127.0.0.1:3000

API Credentials

When you create a widget, two credentials are generated:

Credential	Format	Purpose
API Key	widget-XXXXXX...	Used to authenticate your widget with the Traise API. Pass this to init().
Signing Secret	webhook-XXXXXX...	Used to verify webhook payloads are from Traise.

Important: These credentials are only displayed once when the widget is created. Store them securely. If you lose them, you can regenerate new credentials (which will invalidate the old ones).

Managing Widgets

Editing a Widget

1. Go to Settings > Widgets
2. Click on the widget you want to edit
3. Modify the settings as needed
4. Click Save

Note: Changing the phone number will affect ongoing conversations.

Regenerating API Credentials

If your credentials are compromised or lost:

1. Go to Settings > Widgets
2. Click on the widget
3. Click Regenerate API Key
4. Confirm the action
5. Copy the new credentials

Warning: Regenerating credentials will immediately invalidate the old API key. Update your integration code before the old key stops working.

Deleting a Widget

1. Go to Settings > Widgets
2. Click on the widget
3. Click Delete
4. Confirm the deletion

Warning: Deleting a widget is permanent and cannot be undone. The assigned phone number will be released back to your pool.

Plan Limits

Your Traise plan determines how many widgets you can create:

• The widget list shows your current usage (e.g., "2/5 widgets")
• The Create Widget button is disabled when you've reached your limit
• Contact support to upgrade your plan if you need more widgets

Widget Status

Each widget displays its current status:

Status	Description
Active	Widget is operational and can make/receive calls and messages
Inactive	Widget is disabled and will not function

Verification Status

Your widget card also shows the verification status of your business profile:

Status	Description
Approved	Your profile is verified and ready for production use
Pending	Verification is in progress
Rejected	Verification was not successful - contact support

Next Steps

After creating your widget:

1. Install the widget in your application
2. Configure the widget with your settings
3. Review the API Reference for available functions

Troubleshooting

"Create Widget" button is disabled

You've reached your plan's widget limit. Upgrade your plan or delete an unused widget.

Phone number not appearing in dropdown

The phone number may already be assigned to another widget or location. Each phone number can only be assigned to one widget at a time.

Widget not working on my domain

Ensure your domain is added to the Allowed Domains list, including the correct protocol (https:// or http://).

API key not working

• Verify you copied the complete API key
• Check that the key hasn't been regenerated
• Ensure your domain is whitelisted