Voice Engagement using the API

Make Bulk Calls

Prerequisites

1. Validate a caller id under “Account”, “Telephony”, “Caller IDs”
   1. Retrieve the UUID from the URL to be used when creating the engagement activity. See “caller-id” relationship below example.
2. Create and retrieve API Token under “Developer”, “API Tokens”
   1. Use as basic authorization header, example below
   2. Construct string separated by a colon “user:pass” and then base64 encode. See: https://tools.ietf.org/html/rfc7617
3. Retrieve account key from “Account”, “Settings”, “General” (e.g., “firstbank”)
   1. Use as `X-Account-Key` header

API Documentation

Creating a voice engagement requires the following:

1. Create a voice template: https://omnigage.docs.apiary.io/#reference/call-resources/voice-template
   1. Note: Retrieve the voice template ID to be used when creating the trigger.
2. Create an engagement: https://omnigage.docs.apiary.io/#reference/engagement-resources/engagement-collection/create-engagement
   1. Note: Retrieve the engagement ID to be used when creating the activity, triggers, and envelopes.
3. Create an activity: https://omnigage.docs.apiary.io/#reference/engagement-resources/activity-collection/create-activity
   1. Note: Requires the engagement ID and caller ID.
4. Create a trigger: https://omnigage.docs.apiary.io/#reference/engagement-resources/trigger-collection/create-trigger
   1. Note: Requires activity ID and voice template ID
5. Create envelopes: https://omnigage.docs.apiary.io/#reference/engagement-resources/envelope-collection/create-envelope
   1. Note: See the example below for creating bulk requests using headers `Content-Type` and `Accept` of  `application/vnd.api+json; ext=bulk`

Example Requests

1. Create a Voice Template

POST /api/v1/voice-templates
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z
{
    "data": {
        "type": "voice-templates",
        "attributes": {
            "subject": "Weekly Specials",
            "kind": "text",
            "body": "Hello {{first-name}}, voice template support variables.",
            "voice": "Polly-Brian"
        }
    }
}

2. Create Engagement

POST /api/v1/engagements
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z
{
    "data": {
        "type": "engagements",
        "attributes": {
            "name": "Voice Blast",
	    "direction": "outbound"
        }
    }
}

3. Create an Activity

POST /api/v1/activities
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z
{
    "data": {
        "type": "activities",
        "attributes": {
            "name": "Voice Blast",
            "kind": "voice"
        },
        "relationships": {
            "engagement": {
                "data": {"type": "engagements", "id": "cu8Eo9RyrUsV4MXEiDZpLM"}
            },
            "caller-id": {
                "data": {"type": "caller-ids", "id": "Lv8UgucPVGWcwZd9Hre9dn"}
            }
        }
    }
}

4. Create a Trigger for Machine

POST /api/v1/triggers
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z
{
    "data": {
        "type": "triggers",
        "attributes": {
            "kind": "say",
            "on-event": "voice-machine"
        },
        "relationships": {
            "activity": {
                "data": {"type": "activities", "id": "cu8Eo9RyrUsV4MXEiDZpLM"}
            },
            "voice-template": {
                "data": {"type": "voice-templates", "id": "RyrUsV4MXEicu8Eo9DZpLM"}
            }
        }
    }
}

5. Create a Trigger for Human

POST /api/v1/triggers
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z
{
    "data": {
        "type": "triggers",
        "attributes": {
            "kind": "say",
            "on-event": "voice-human"
        },
        "relationships": {
            "activity": {
                "data": {"type": "activities", "id": "cu8Eo9RyrUsV4MXEiDZpLM"}
            },
            "voice-template": {
                "data": {"type": "voice-templates", "id": "RyrUsV4MXEicu8Eo9DZpLM"}
            }
        }
    }
}

6. Create Envelopes

POST /api/v1/envelopes
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z
Content-Type: application/vnd.api+json; ext=bulk
Accept: application/vnd.api+json; ext=bulk
{
    "data": [{
        "type": "envelopes",
        "attributes": {
            "phone-number": "+15197566220",
            "meta": {
                "first-name": "Alexander",
                "last-name": "Bell"
            }
        },
        "relationships": {
            "engagement": {
                "data": {"type": "engagements", "id": "yrbCdxqV2ZMdQBCszhA7TZ"}
            }
        }
    },
    {
        "type": "envelopes",
        "attributes": {
            "phone-number": "+19734390088",
            "meta": {
                "first-name": "Michael",
                "last-name": "Morgan"
            }
        },
        "relationships": {
            "engagement": {
                "data": {"type": "engagements", "id": "yrbCdxqV2ZMdQBCszhA7TZ"}
            }
        }
    }]
}

7. Submit Engagement for Processing

PATCH /api/v1/engagements/yrbCdxqV2ZMdQBCszhA7TZ
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z
{
   "data":{
      "id": "yrbCdxqV2ZMdQBCszhA7TZ",
      "type": "engagements",
      "attributes": {
         "status": "scheduled",
         "delivery-type": "immediately"
      }
   }
}