Skip to main content
Get the Consuelo bot running in your Discord server in minutes.
This guide walks you through everything you need to get started with the Consuelo Discord bot — from inviting it to your server to making your first call.

​
Prerequisites

Before you begin, make sure you have:
  • A Consuelo workspace with an active subscription (or self-hosted instance)
  • Admin or owner access to a Discord server
  • Your Consuelo API key (we’ll show you where to find this)
  • Your workspace ID and user ID

​
Step 1: Invite the Bot

The bot invite link is provided by your Consuelo admin or can be generated from your workspace settings. For Cloud-hosted Consuelo:
  1. Log into your Consuelo workspace
  2. Go to Settings → Integrations → Discord
  3. Click Generate Invite Link
  4. Copy the provided URL
For Self-Hosted: If you’re self-hosting Consuelo, you’ll need to create a Discord application first:
  1. Go to the Discord Developer Portal
  2. Click New Application and give it a name (e.g., “Consuelo Bot”)
  3. Navigate to OAuth2 → URL Generator
  4. Select the following scopes:
    • bot
    • applications.commands
  5. Select these bot permissions:
    • Send Messages
    • Read Message History
    • Add Reactions
    • Use Slash Commands
    • Manage Channels (optional, for channel notifications)
  6. Copy the generated URL

​
1.2 Invite to Your Server

  1. Open the invite link in your browser
  2. Select your Discord server from the dropdown
  3. Review the permissions being requested
  4. Click Authorize
  5. Complete the CAPTCHA verification
  6. You should see a success message: “Authorized!“

​
1.3 Verify the Bot Joined

In your Discord server:
  1. Check the member list — you should see the bot (usually named “Consuelo”)
  2. Try typing /consuelo — you should see the command suggestions appear
  3. Run /consuelo ping to verify it’s responding
If the bot doesn’t respond:
  • Check that the bot has permission to view and send messages in the channel
  • Verify your server hasn’t reached the bot limit (max 50 bots per server)
  • Ensure the bot token hasn’t expired (contact your admin if self-hosting)
Server Permissions Required The bot needs these minimum permissions to function: - Send Messages - Embed Links - Read Message History - Use Slash Commands For channel notifications, it also needs permission to post in the specific channel.

​
Step 2: Find Your Credentials

Before linking your account, you need three pieces of information from Consuelo.

​
2.1 Get Your Workspace ID

  1. Log into Consuelo
  2. Go to Settings → General
  3. Copy the Workspace ID (looks like 123e4567-e89b-12d3-a456-426614174000)

​
2.2 Get Your User ID

  1. Go to Settings → Profile
  2. Your User ID is displayed at the top (looks similar to workspace ID)
  3. Copy this value

​
2.3 Generate an API Key

  1. Go to Settings → API (or Developer)
  2. Click Generate New Key
  3. Give it a name like “Discord Bot”
  4. Copy the API key immediately — you won’t be able to see it again!
Keep Your API Key Secure - Never share your API key in public channels - Don’t commit it to code repositories - If you lose it, revoke the old one and generate a new key - The bot stores this encrypted, but you should treat it like a password

​
2.4 Set Your Phone Number

The bot needs to know which phone number to call when connecting you to leads.
  1. In Consuelo, go to Settings → Profile
  2. Add your phone number in the Phone field
  3. Use the format: +15551234567 (include country code)
  4. Click Save
Alternative via API: 
curl -X PATCH https://api.consuelohq.com/v1/users/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"phone": "+15551234567"}'
Now that you have your credentials, link your Discord account to Consuelo.

​
3.1 Run the Login Command

In any channel in your Discord server: 
/consuelo login
The bot will respond with a DM or ephemeral message containing a secure link: 
🔗 Link Your Account

Click below to connect your Discord account to your Consuelo workspace.

[Link Account]
The link is ephemeral — only you can see it. For security, this link expires after 10 minutes.

​
3.2 Enter Your Credentials

Click the link to open the secure linking page:
  1. Discord User ID — Pre-filled, don’t change this
  2. Workspace ID — Paste from Step 2.1
  3. User ID — Paste from Step 2.2
  4. API Key — Paste from Step 2.3
Click Link Account

​
3.3 Confirm Success

You should see: 
✅ Account Linked

You can close this window and return to Discord.
Close the browser tab and return to Discord. Run the ping command: 
/consuelo ping
Expected response: 
🏓 Pong!

Version: 0.0.1
Uptime: 2h 15m
Workspace: your-workspace-id
Status: Online
If you see workspace information, your account is linked correctly!

​
Step 4: Test Your Setup

Before starting real calls, verify everything is working.

​
4.1 Check System Status

/consuelo status
Should show all services as ✅: 
📊 System Status
API: Online
Active Queue: None
Current Call: None

✅ Dialer
✅ API
✅ Queue Engine

/consuelo contacts search test
Should return contacts from your workspace or “No Results” (not an error).

​
4.3 View Your Stats

/consuelo me
Should show your calling statistics: 
👤 John Smith (You)

Calls Today: 0
Calls This Week: 0
Connect Rate: 0%
Avg Duration: 0s

​
Step 5: Configure Notifications (Optional)

Set up automatic notifications for your team.

​
5.1 Choose a Channel

Pick or create a channel for call notifications (e.g., #call-activity).

​
5.2 Check Permissions

Ensure the bot can post in that channel:
  1. Right-click the channel → Edit Channel → Permissions
  2. Find the Consuelo bot role
  3. Verify Send Messages and Embed Links are allowed

​
5.3 Set the Channel

You must be a workspace admin to set the notification channel: 
/consuelo config channel #call-activity
Success response: 
✅ Channel Set

Notifications will be posted to #call-activity.

​
What Gets Posted

Once configured, the channel will receive:
  • Call Started — When you begin a call
  • Call Ended — When you finish a call (with duration and outcome)
  • Transfer Requests — When you request help from a manager
  • Queue Summary — When you complete a queue

​
Step 6: Make Your First Call

You’re ready to start calling!

​
6.1 Start a Queue

/consuelo queue start
The bot will:
  1. Find an available queue in your workspace
  2. Call your phone
  3. When you answer, connect you to the first lead

​
6.2 During the Call

Use the CRM dialer or Discord commands:
  • /consuelo transfer @manager — For help
  • /consuelo whisper @manager — For silent coaching

​
6.3 After the Call

An interactive card appears with disposition options: 
📋 Call Summary
Lead: John Smith — (555) 123-4567
Duration: 3m 42s

[Connected] [Voicemail] [No Answer]
[Busy] [Follow-up] [Not Interested]
Click the outcome that matches your call.

​
6.4 Continue or Stop

  • Power mode: Next call starts automatically
  • Preview mode: Use /consuelo queue call when ready
  • Stop anytime: /consuelo queue stop

​
Troubleshooting

​
Bot Not Responding

Problem: /consuelo commands don’t work Solutions:
  1. Check that the bot is online in your server’s member list
  2. Verify the bot has permission to view the channel
  3. Try @Consuelo ping to test mentions
  4. Re-invite the bot if necessary

​
”Not Linked” Error

Problem: Commands fail with “Not Linked” message Solutions:
  1. Run /consuelo login again
  2. Verify you entered the correct workspace ID and user ID
  3. Check that your API key hasn’t been revoked
  4. Ensure you’re using the correct Discord account

​
”Missing Phone Number” Error

Problem: Can’t start queues Solutions:
  1. Go to Consuelo Settings → Profile
  2. Add your phone number with country code (e.g., +15551234567)
  3. Wait 1-2 minutes for the cache to refresh
  4. Try again

​
”Unauthorized” Error

Problem: API returns 401 errors Solutions:
  1. Your API key may have expired or been revoked
  2. Go to Consuelo Settings → API
  3. Revoke the old key and generate a new one
  4. Run /consuelo logout then /consuelo login

​
Can’t Set Notification Channel

Problem: /consuelo config channel fails Solutions:
  1. Verify you’re a workspace admin in Consuelo
  2. Check that the bot has “Send Messages” permission in the channel
  3. Try using the channel ID instead of the mention: 1234567890123456789
  4. The bot may need “Manage Webhooks” permission for some features

​
Next Steps

Now that you’re set up:
  1. Learn queue management: Queue Management Guide
  2. Master transfers: Call Controls
  3. Set up team collaboration: Team Features

​
Getting Help

If you encounter issues:
  • Check this guide — Most common issues are covered above
  • Contact your workspace admin — They can verify your permissions and API keys
  • Reach out to Consuelo support — For cloud-hosted issues
  • Check Discord status — Ensure Discord’s API is operational
The bot logs errors to help with debugging. If you report an issue to support, include the exact error message and what command you were running.