DGA Deployment API - Version 1.2 Documentation

Overview

The V1.2 deployment endpoint provides enhanced functionality for deploying Techwall campaigns with improved error handling and flexible phone number configuration.

Endpoint

POST https://5ik98b5l88.execute-api.us-east-1.amazonaws.com/default/dga_deployment_api

Request Format

Headers

Content-Type: application/json

Request Body

{
  "campaign_id": 2737,
  "version": "v2",
  "phone_number": "+19413474929"  // Optional
}

Parameters

Parameter	Type	Required	Description
campaign_id	integer	Yes	The campaign ID from the DGA system
version	string	Yes	Must be set to "v2" to use the V1.2 endpoint
phone_number	string	No	Phone number in format: +1XXXXXXXXXX or XXXXXXXXXX

Phone Number Behavior

When to Include phone_number

You should include the phone_number parameter in the following scenarios:

1. Migrating Old Dealerships

   • When migrating existing dealerships to the new system
   • Ensures continuity with their existing phone infrastructure

2. Custom Phone Number Requirements

   • When the dealership wants to use a different phone number than what's configured in their DGA campaign data
   • When testing with a specific phone number

3. Override Scenarios

   • When the inbound_dnis field in the campaign data is incorrect or needs to be overridden

When to Omit phone_number

You can omit the phone_number parameter when:

1. New Deployments

   • The phone number configured in the DGA campaign data (inbound_dnis field) is correct
   • You want to use the default phone number from the campaign configuration

2. Standard Deployments

   • No special phone number requirements exist
   • The campaign data already contains the correct phone information

Fallback Behavior

If phone_number is not provided, the system will automatically:

1. Look for the inbound_dnis field in the campaign data
2. Use that value as the phone number for deployment
3. Validate and format the phone number appropriately

If no valid phone number can be found in either the request or campaign data, the deployment will fail with an error message.

Phone Number Format

The API accepts phone numbers in multiple formats and automatically normalizes them:

• +14155551234 (with country code)
• 4155551234 (without country code)
• (415) 555-1234 (formatted)
• 415-555-1234 (with dashes)

All formats will be normalized to +1XXXXXXXXXX format internally.

Response Format

Success Response

Status Code: 200 OK

{
  "statusCode": 200,
  "headers": {
    "Content-Type": "application/json",
    "Access-Control-Allow-Origin": "*"
  },
  "body": {
    "message": {
      "status": "success",
      "message": "Deployment completed successfully",
      "phone_number": "+19413474929",
      "subdomain": "dealership-name"
    },
    "campaign_id": 2737
  }
}

Error Response

Status Code: 500 (for deployment errors) or 400 (for validation errors)

{
  "statusCode": 500,
  "headers": {
    "Content-Type": "application/json",
    "Access-Control-Allow-Origin": "*"
  },
  "body": {
    "error": "Error message describing what went wrong"
  }
}

Error Messages

The V2 endpoint provides detailed error messages for different failure scenarios:

Error Type	Example Message
Missing Data	"No campaign data provided for deployment"
Phone Validation	"Phone number validation failed: Invalid phone number format"
Missing URL	"Missing virtual_agent_url in campaign data"
Database Connection	"Database connection failed: [details]"
Database Operation	"Database insert/update failed: [details]"
Template Creation	"Error creating deployment template: [details]"
Template Deployment	"Template deployment API request failed: [details]"

Example Requests

Example 1: Migrating Old Dealership (with custom phone number)

curl -X POST https://5ik98b5l88.execute-api.us-east-1.amazonaws.com/default/dga_deployment_api \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": 2737,
    "version": "v2",
    "phone_number": "+19413474929"
  }'

Example 2: New Deployment (using campaign data phone number)

curl -X POST https://5ik98b5l88.execute-api.us-east-1.amazonaws.com/default/dga_deployment_api \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": 2737,
    "version": "v2"
  }'

Example 3: Using Node.js/JavaScript

const response = await fetch('https://5ik98b5l88.execute-api.us-east-1.amazonaws.com/default/dga_deployment_api', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    campaign_id: 2737,
    version: 'v2',
    phone_number: '+19413474929'  // Optional
  })
});

const result = await response.json();
console.log(result);

Example 4: Using Python

import requests

response = requests.post(
    'https://5ik98b5l88.execute-api.us-east-1.amazonaws.com/default/dga_deployment_api',
    json={
        'campaign_id': 2737,
        'version': 'v2',
        'phone_number': '+19413474929'  # Optional
    }
)

result = response.json()
print(result)

Migration Best Practices

When migrating old dealerships to the V1.2 system:

1. Always include the phone number explicitly

   • Ensures the correct phone number is used
   • Avoids relying on potentially outdated campaign data

2. Verify the phone number format

   • Ensure the phone number is valid before making the request
   • The API will validate, but catching errors early is better

3. Test with a single dealership first

   • Validate the migration process works correctly
   • Check that the phone number is properly configured

4. Monitor the response

   • Check for success status
   • Log any error messages for troubleshooting

5. Keep records

   • Document which phone number was used for each migration
   • Maintain a mapping of campaign_id to phone_number

Differences from V1

Feature	V1	V1.2
Phone Number Support	Uses campaign data only	Accepts optional phone_number parameter
Error Handling	Basic error messages	Detailed error messages for each failure point
Database Cleanup	Not guaranteed	Automatic cleanup in finally block
Validation	Limited	Comprehensive validation at each step
Flexibility	Fixed configuration	Flexible phone number configuration

Technical Details

What Happens During Deployment

1. Validation Phase

   • Validates campaign data exists
   • Validates or retrieves phone number
   • Extracts subdomain from virtual_agent_url

2. Database Phase

   • Connects to PostgreSQL database
   • Inserts/updates dealership record
   • Commits transaction or rolls back on error

3. Template Phase

   • Fetches campaign data
   • Formats prompt and configuration
   • Creates deployment template

4. Deployment Phase

   • Sends template to Brainbase API
   • Validates response
   • Returns success or detailed error

Error Handling

Each phase has specific error handling:

• Database connections are automatically closed in finally block
• Failed database operations trigger automatic rollback
• All errors return descriptive messages via API response
• Stack traces are logged for debugging

Support

For issues or questions about the V2 API:

• Check error messages first - they provide specific details
• Review CloudWatch logs for detailed stack traces
• Verify campaign data is correct in the DGA system
• Ensure phone numbers are in valid format

Version History

• V2 - Added flexible phone number support, comprehensive error handling
• V1 - Initial deployment API