Troubleshooting

This guide helps you resolve common issues you might encounter while using Smobi. If you can’t find a solution here, please contact our support team.

Common Issues

Message Delivery Issues

Messages Not Being Delivered

Symptoms: Messages show as “FAILED” or “REJECTED” status

Possible Causes and Solutions:

1. Invalid Phone Number Format

   • Issue: Phone number is not in the correct format
   • Solution: Use E.164 format (e.g., +15552223333)
   • Check: Verify phone number includes country code

2. Phone Number Not Added to Test Numbers

   • Issue: Trying to send to a number not in your test list
   • Solution: Add the phone number to your test numbers in brand settings
   • Check: Go to Settings → Your Brand → Test Numbers

3. RCS Approval Pending

   • Issue: Brand is not yet approved for RCS messaging
   • Solution: Wait for RCS approval (4-6 weeks) or use SMS only
   • Check: Verify brand approval status in dashboard

4. Rate Limits Exceeded

   • Issue: Sending too many messages too quickly
   • Solution: Implement rate limiting in your application
   • Check: Monitor your message sending rate

Messages Delivered but Not Read

Symptoms: Messages show as “DELIVERED” but not “READ”

Possible Causes and Solutions:

1. Recipient’s Phone Settings

   • Issue: Recipient has disabled read receipts
   • Solution: This is normal behavior - not all phones support read receipts
   • Check: Focus on delivery rate rather than read rate

2. Message Content Issues

   • Issue: Message content may not be engaging
   • Solution: Improve message content and add interactive elements
   • Check: Test different message formats and content

Workflow Issues

Workflow Not Starting

Symptoms: Workflow execution fails to begin

Possible Causes and Solutions:

1. Workflow Not Published

   • Issue: Workflow is in draft status
   • Solution: Publish the workflow before executing
   • Check: Verify workflow status in the workflow builder

2. Invalid Workflow ID

   • Issue: Using incorrect workflow definition ID
   • Solution: Copy the correct workflow ID from the dashboard
   • Check: Verify workflow ID in the workflows list

3. API Key Issues

   • Issue: Invalid or expired API key
   • Solution: Generate a new API key in brand settings
   • Check: Verify API key in your application

Workflow Stuck or Not Completing

Symptoms: Workflow starts but doesn’t complete

Possible Causes and Solutions:

1. Condition Node Issues

   • Issue: Conditional logic is not working as expected
   • Solution: Review condition configuration and test with different inputs
   • Check: Use workflow testing tools to debug conditions

2. Message Node Failures

   • Issue: Messages in workflow are failing to send
   • Solution: Check message content and recipient phone numbers
   • Check: Review message delivery status in analytics

3. Variable Issues

   • Issue: Variables are not being populated correctly
   • Solution: Verify variable names and values
   • Check: Use workflow testing to inspect variable values

API Integration Issues

Authentication Errors

Symptoms: Receiving 401 Unauthorized errors

Possible Causes and Solutions:

1. Invalid API Key

   • Issue: API key is incorrect or expired
   • Solution: Generate a new API key in brand settings
   • Check: Verify API key is copied correctly

2. Missing API Key

   • Issue: API key not included in request headers
   • Solution: Include API key in x-api-key header
   • Check: Verify request headers in your code

3. Wrong Environment

   • Issue: Using production API key in development or vice versa
   • Solution: Use the correct API key for your environment
   • Check: Verify environment configuration

Rate Limiting Errors

Symptoms: Receiving 429 Too Many Requests errors

Possible Causes and Solutions:

1. Exceeding Rate Limits

   • Issue: Sending too many requests too quickly
   • Solution: Implement exponential backoff and retry logic
   • Check: Monitor your request rate

2. Batch Size Too Large

   • Issue: Sending too many items in a single batch
   • Solution: Reduce batch size to stay within limits
   • Check: Review batch size limits in API documentation

Webhook Issues

Webhooks Not Being Received

Symptoms: No webhook events reaching your endpoint

Possible Causes and Solutions:

1. Endpoint Not Accessible

   • Issue: Webhook URL is not publicly accessible
   • Solution: Ensure your endpoint is accessible via HTTPS
   • Check: Test webhook URL accessibility

2. Incorrect Webhook URL

   • Issue: Webhook URL is incorrect in brand settings
   • Solution: Update webhook URL in brand settings
   • Check: Verify webhook configuration

3. Firewall or Network Issues

   • Issue: Network blocking webhook requests
   • Solution: Check firewall settings and network configuration
   • Check: Test webhook endpoint from external sources

Webhook Signature Verification Failures

Symptoms: Webhook signature verification failing

Possible Causes and Solutions:

1. Incorrect Webhook Secret

   • Issue: Webhook secret doesn’t match
   • Solution: Verify webhook secret in your application
   • Check: Compare webhook secret with brand settings

2. Payload Format Issues

   • Issue: Payload format has changed
   • Solution: Update webhook handler to match current format
   • Check: Review webhook payload documentation

Brand Setup Issues

Brand Registration Problems

Symptoms: Unable to complete brand registration

Possible Causes and Solutions:

1. Missing Required Fields

   • Issue: Required fields not completed
   • Solution: Fill in all required fields in the brand form
   • Check: Review brand registration form

2. Image Format Issues

   • Issue: Logo or header images don’t meet requirements
   • Solution: Use PNG/JPG format, correct dimensions, and file size
   • Check: Verify image requirements (max 5MB, correct dimensions)

3. Website URL Issues

   • Issue: Website URL is not accessible
   • Solution: Ensure website is publicly accessible
   • Check: Test website URL in browser

RCS Approval Delays

Symptoms: RCS approval taking longer than expected

Possible Causes and Solutions:

1. Normal Processing Time

   • Issue: RCS approval typically takes 4-6 weeks
   • Solution: Wait for approval process to complete
   • Check: Monitor approval status in dashboard

2. Incomplete Brand Information

   • Issue: Brand information may be incomplete
   • Solution: Ensure all brand information is complete and accurate
   • Check: Review and update brand information

Error Codes and Meanings

API Error Codes

Message Status Codes

Debugging Tools

API Debugging

Enable Debug Logging

1
// Enable debug logging in your application
2
const client = new SmobiClient({
3
  apiKey: process.env.SMOBI_API_KEY,
4
  debug: true // Enable debug logging
5
});

Check Request/Response

1
// Log request and response details
2
try {
3
  const result = await client.messages.send(messageData);
4
  console.log('Request successful:', result);
5
} catch (error) {
6
  console.error('Request failed:', {
7
    status: error.status,
8
    message: error.message,
9
    details: error.details
10
  });
11
}

Workflow Debugging

Use Workflow Testing

1. Test with Personal Number: Use your phone number for testing
2. Step-by-Step Execution: Execute workflows one node at a time
3. Variable Inspection: Check variable values at each step
4. Execution Logs: Review detailed execution logs

Common Debugging Steps

1. Verify Workflow Status: Ensure workflow is published
2. Check Node Configuration: Verify all nodes are properly configured
3. Test Variables: Ensure variables are being populated correctly
4. Monitor Execution: Watch real-time execution in workflow builder

Webhook Debugging

Test Webhook Endpoint

1
// Test webhook endpoint accessibility
2
async function testWebhookEndpoint() {
3
  try {
4
    const response = await fetch('https://your-webhook-endpoint.com/webhook', {
5
      method: 'POST',
6
      headers: { 'Content-Type': 'application/json' },
7
      body: JSON.stringify({ test: true })
8
    });
9
    
10
    console.log('Webhook test response:', response.status);
11
    return response.ok;
12
  } catch (error) {
13
    console.error('Webhook test failed:', error);
14
    return false;
15
  }
16
}

Monitor Webhook Delivery

1. Check Server Logs: Monitor your webhook endpoint logs
2. Verify HTTPS: Ensure endpoint uses HTTPS
3. Test Signature: Verify webhook signature validation
4. Check Response: Ensure endpoint returns 200 status code

Performance Optimization

Message Sending Optimization

Batch Processing

1
// Use batch operations for multiple messages
2
const batchResult = await client.workflows.executeWorkflowBatch(
3
  workflowId,
4
  {
5
    executions: phoneNumbers.map(phone => ({
6
      phoneNumber: phone,
7
      variables: { customerName: "Customer" }
8
    }))
9
  }
10
);

Rate Limiting

1
// Implement rate limiting
2
class RateLimiter {
3
  private queue: Array<() => Promise<any>> = [];
4
  private processing = false;
5
  private rateLimit = 100; // requests per minute
6
  
7
  async addRequest(request: () => Promise<any>) {
8
    return new Promise((resolve, reject) => {
9
      this.queue.push(async () => {
10
        try {
11
          const result = await request();
12
          resolve(result);
13
        } catch (error) {
14
          reject(error);
15
        }
16
      });
17
      
18
      if (!this.processing) {
19
        this.processQueue();
20
      }
21
    });
22
  }
23
  
24
  private async processQueue() {
25
    this.processing = true;
26
    
27
    while (this.queue.length > 0) {
28
      const request = this.queue.shift();
29
      if (request) {
30
        await request();
31
        await new Promise(resolve => setTimeout(resolve, 60000 / this.rateLimit));
32
      }
33
    }
34
    
35
    this.processing = false;
36
  }
37
}

Workflow Optimization

Efficient Variable Usage

• Minimize Variables: Use only necessary variables
• Optimize Conditions: Use simple, efficient conditional logic
• Reduce Delays: Minimize unnecessary delays in workflows
• Monitor Performance: Track workflow execution times

Caching Strategies

1
// Cache frequently accessed data
2
const cache = new Map();
3
4
async function getCachedData(key: string, fetchFunction: () => Promise<any>) {
5
  if (cache.has(key)) {
6
    return cache.get(key);
7
  }
8
  
9
  const data = await fetchFunction();
10
  cache.set(key, data);
11
  return data;
12
}

Getting Help

When to Contact Support

Contact our support team if you encounter:

1. Persistent API Errors: Errors that continue after troubleshooting
2. Service Outages: Platform-wide issues affecting your service
3. Security Concerns: Suspected security issues or breaches
4. Feature Requests: Questions about platform capabilities
5. Account Issues: Problems with account access or billing

Information to Provide

When contacting support, please provide:

1. Error Details: Complete error messages and codes
2. Reproduction Steps: Steps to reproduce the issue
3. Environment Information: API keys, environment, timestamps
4. Logs: Relevant application logs and error details
5. Expected vs Actual Behavior: What you expected vs what happened

Support Channels

• Email: support@smobi.com
• Documentation: Check this troubleshooting guide first
• Community: Join our developer community for peer support
• Status Page - Check platform status for known issues

Prevention Best Practices

Proactive Monitoring

Set Up Alerts

1
// Monitor API usage and errors
2
class APIMonitor {
3
  private errorCount = 0;
4
  private lastErrorTime = 0;
5
  
6
  async monitorRequest(request: () => Promise<any>) {
7
    try {
8
      const result = await request();
9
      this.resetErrorCount();
10
      return result;
11
    } catch (error) {
12
      this.handleError(error);
13
      throw error;
14
    }
15
  }
16
  
17
  private handleError(error: any) {
18
    this.errorCount++;
19
    this.lastErrorTime = Date.now();
20
    
21
    if (this.errorCount > 10) {
22
      this.sendAlert('High error rate detected');
23
    }
24
  }
25
  
26
  private resetErrorCount() {
27
    this.errorCount = 0;
28
  }
29
  
30
  private sendAlert(message: string) {
31
    // Send alert to your monitoring system
32
    console.error('ALERT:', message);
33
  }
34
}

Regular Health Checks

• API Connectivity: Test API connectivity regularly
• Webhook Delivery: Monitor webhook delivery success rates
• Message Delivery: Track message delivery rates
• Workflow Performance: Monitor workflow completion rates

Documentation and Logging

Comprehensive Logging

1
// Implement comprehensive logging
2
class Logger {
3
  log(level: string, message: string, data?: any) {
4
    const logEntry = {
5
      timestamp: new Date().toISOString(),
6
      level,
7
      message,
8
      data,
9
      environment: process.env.NODE_ENV
10
    };
11
    
12
    console.log(JSON.stringify(logEntry));
13
    
14
    // Send to external logging service
15
    this.sendToLogService(logEntry);
16
  }
17
  
18
  private sendToLogService(logEntry: any) {
19
    // Send to your logging service (e.g., DataDog, LogRocket)
20
  }
21
}

Documentation

• API Usage: Document your API integration patterns
• Error Handling: Document error handling strategies
• Configuration: Document environment configuration
• Procedures: Document troubleshooting procedures

Next Steps

• Quick Start Guide - Review basic setup
• TypeScript SDK - Check SDK usage
• Webhooks Setup - Verify webhook configuration
• Testing & Playground - Use testing tools
• Support & Resources - Get additional help