Applications
An Application is a set of Answer, Hangup, and Message URLs that help you control your incoming calls and messages.
Key Concepts
Answer URL
Vobiz requests this URL for a valid Vobiz XML element on an incoming call. The XML returned by this URL determines the flow of the call.
Hangup URL
Vobiz will make an HTTP request to this URL when the call is hung up. Useful for call analytics and cleanup operations.
Message URL
Vobiz will send all incoming messages to this URL. We expect to receive an HTTP status code of 200 from this URL.
SIP URI
All Vobiz applications can be called directly without attaching them to a number or an endpoint. When an incoming call is received on this URI, Vobiz follows the same flow as it does with a number or an endpoint.
Application Operations
The Application Object
View the structure and attributes of the Application object including URLs, methods, and default settings.
Create an Application
POST request to create a new application with answer URL, hangup URL, and message URL configuration.
Retrieve an Application
GET request to retrieve all details of a specific application by app_id.
Update an Application
POST request to modify application settings. Unspecified parameters remain unchanged.
Delete an Application
DELETE request to permanently remove an application. Optionally cascade delete associated endpoints.
List All Applications
GET request to retrieve all applications with optional filtering and pagination support.
Webhook Callbacks
Answer URL Callback
When a call is answered, Vobiz makes a request to your answer_url with call details.
Request Parameters:
POST https://example.com/answer Content-Type: application/x-www-form-urlencoded CallUUID=abc123&From=14155551234&To=14155556789&Direction=inbound&CallStatus=ringing
Expected Response (XML):
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Speak>Welcome to our service</Speak>
<Gather numDigits="1" action="https://example.com/gather">
<Speak>Press 1 for sales, 2 for support</Speak>
</Gather>
</Response>Hangup URL Callback
When a call ends, Vobiz notifies your hangup_url with call details and duration.
Request Parameters:
POST https://example.com/hangup Content-Type: application/x-www-form-urlencoded CallUUID=abc123&CallStatus=completed&Duration=45&HangupCause=NORMAL_CLEARING
Best Practices
Always Use HTTPS
All webhook URLs (answer_url, hangup_url, etc.) must use HTTPS for security.
Handle Retries
Vobiz retries failed webhook calls up to 3 times. Ensure idempotent operations.
Respond Quickly
Answer URL must respond within 10 seconds to avoid call timeout.
Validate Webhooks
Verify requests are from Vobiz using signature validation.
Use Fallback URLs
Always configure fallback_answer_url for production apps to handle failures.
Test in Development
Use test account before deploying to production environment.
Monitor Usage
Check which numbers/endpoints use each app before deletion.