Text Engagement using the API

Send Bulk Text

Prerequisites

Purchase a phone number under “Account”, “Telephony”, “Phone Numbers”
1. Retrieve the UUID from the URL to be used when creating the engagement activity. See “phone-number” relationship in below example.
Create and retrieve API Token under “Developer”, “API Tokens”
1. Use as basic authorization header, example below
2. Construct string separated by colon “user:pass” and then base64 encode. See: https://tools.ietf.org/html/rfc7617
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:

Create a text template: https://omnigage.docs.apiary.io/#reference/text-resources/text-template-collection/create-text-template
1. Note: Retrieve the text template ID to be used when creating the trigger.
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 and envelopes.
Create an activity: https://omnigage.docs.apiary.io/#reference/engagement-resources/activity-collection/create-activity
1. Note: Requires the engagement ID, phone number ID, and text template ID
Create envelopes: https://omnigage.docs.apiary.io/#reference/engagement-resources/envelope-collection/create-envelope
1. Note: See example below for creating bulk requests using headers `Content-Type` and `Accept` of `application/vnd.api+json; ext=bulk`

Example Requests

1. Create Text Template

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

2. Create Engagement

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

3. Create Activity

POST /api/v1/activities
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z
{
    "data": {
        "type": "activities",
        "attributes": {
            "name": "Text Blast",
            "kind": "text"
        },
        "relationships": {
            "engagement": {
                "data": {"type": "engagements", "id": "cu8Eo9RyrUsV4MXEiDZpLM"}
            },
            "text-template": {
                "data": {"type": "text-templates", "id": "iDZpLM8Eo9RyrUsV4MXE"}
            },
            "phone-number": {
                "data": {"type": "phone-numbers", "id": "Lv8UgucPVGWcwZd9Hre9dn"}
            }
        }
    }
}

4. 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"}
            }
        }
    }]
}

5. 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"
      }
   }
}