Skip to end of metadata
Go to start of metadata

Last Updated: Tuesday, July 16, 2019



Broadcast APIs are used to Create, Get, Update, Cancel/Delete, and Search for Broadcasts.

Search/Get Broadcasts

The following will return up to the first 100 Broadcasts within the Mobile Database.

GET /companies/:company_key/mobiledb/broadcasts[?status=:status]
Note: To get your company ID, please contact your Vibes account manager.

If a status is specified, only Broadcasts with that status will be returned. If no status is specified, it will default to scheduled status.

The following are valid status values (always lowercase):

  • scheduled
  • sent
  • canceled
  • in_progress
  • failed
  • paused
  • deleted

Request JSON

There is no Request JSON with a GET.

Return JSON

An array of Broadcast objects, up to a maximum of 100.

[
  {
    "broadcast_id": "1",
    "status": "sent",
    "name": "First alert message",
    "send_scheduled_date": "2017-04-04T16:05:00Z",
    "created_by": "user@company.com",
    "created_by_application": null,
    "targeting": {
      "message_template": "This is the 1st message sent to the {{ list_name }} list!",
      "short_url_base": "http://vbs.cm/",
      "shorten_urls": true,
      "channel": "sms",
      "source_short_code": null,
      "source_lists": [
        "123"
      ],
      "filters": []
    },
    "delivery": {
      "send_start_date": "2017-04-04T16:06:16Z",
      "enqueue_completed_date": "2017-04-04T16:06:16Z",
      "recipient_count": 1
    },
    "url": "/companies/:company_key/mobiledb/broadcasts/:broadcast_id",
    "created_at": "2017-04-04T16:06:10Z",
    "updated_at": "2019-05-12T05:09:48Z"
  }
]

Get a Broadcast

The following will return the Broadcast entity specified by the given :broadcast_id.

GET /companies/:company_key/mobiledb/broadcasts/:broadcast_id

Request JSON

There is no Request JSON with a GET.

Return JSON

A Broadcast object.

{
  "broadcast_id": "1",
  "status": "sent",
  "name": "First alert message",
  "send_scheduled_date": "2017-04-04T16:05:00Z",
  "created_by": "user@company.com",
  "created_by_application": null,
  "targeting": {
    "message_template": "This is the 1st message sent to the {{ list_name }} list!",
    "short_url_base": "http://vbs.cm/",
    "shorten_urls": true,
    "channel": "sms",
    "source_short_code": null,
    "source_lists": [
      "123"
    ],
    "filters": []
  },
  "delivery": {
    "send_start_date": "2017-04-04T16:06:16Z",
    "enqueue_completed_date": "2017-04-04T16:06:16Z",
    "recipient_count": 1
  },
  "url": "/companies/:company_key/mobiledb/broadcasts/:broadcast_id",
  "created_at": "2017-04-04T16:06:10Z",
  "updated_at": "2019-05-12T05:09:48Z"
}
Note: A 404 - Not Found error will be returned if the Broadcast could not be located.

Create a Broadcast

The following will create a new Broadcast entity.

POST /companies/:company_key/mobiledb/broadcasts

Request JSON

A Broadcast entity.

{
   "name": "Test Broadcast SAT 2",
   "status": "scheduled",
   "send_scheduled_date": "2017-02-16T07:30:00Z",
   "created_by": "user@company.com",
   "created_by_application": "my application",
   "targeting": {
      "message_template": "push message content",
      "shorten_urls": true,
      "short_url_base": "http://vbs.cm/",
      "source_short_code": null,
      "source_lists": [
         "123",
         "124"
      ],
	  "channel": "push",
      "push": {
        "subject": "push message title",
        "metadata": "app deep link"
      },
      "filters": [
         {
            "name": "favorite_sport",
            "selector": "any",
            "value": [
               "football",
               "baseball"
            ]
         },
         {
            "name": "first_name",
            "selector": "starts_with",
            "value": "Steven"
         },
         {
            "name": "subscription_date",
            "selector": "before",
            "value": [
               "2017-01-01"
            ]
         }
      ]
   }
}

Return JSON

The url, status, id, created_at, updated_at and delivery fields are defined by the system and cannot be specified in the request.

{
   "broadcast_id": "123456",
   "status": "scheduled",
   "url": "/companies/:company_key/broadcasts/:broadcast_id",
   "name": "Test Broadcast SAT 2",
   "send_scheduled_date": "2017-02-16T07:30:00Z",
   "created_by": "user@company.com",
   "created_by_application": "my application",
   "targeting": {
      "message_template": "push message content",
      "shorten_urls": true,
      "short_url_base": "http://vbs.cm/",
      "source_short_code": "54321",
      "source_lists": [
         "123",
         "124"
      ],
      "filters": [
         {
            "name": "favorite_sport",
            "selector": "any",
            "value": [
               "football",
               "baseball"
            ]
         },
         {
            "name": "first_name",
            "selector": "starts_with",
            "value": "Steven"
         },
         {
            "name": "subscription_date",
            "selector": "before",
            "value": [
               "2017-01-01"
            ]
         }
      ]
   },
   "created_at": "2017-02-11T18:58:53Z",
   "updated_at": "2017-02-11T18:58:53Z"
}
Note: This will return a 201 - Created status code if the Broadcast was successfully created.

Update a Broadcast

The following will update an existing scheduled Broadcast with new data.

PUT /companies/:company_key/mobiledb/broadcasts/:broadcast_id

Only scheduled Broadcasts can be updated.

The url, status, id, created_at, updated_at and delivery fields are defined by the system and cannot be specified in the request.

Request JSON

{
   "name": "Test Broadcast SAT 2",
   "status": "scheduled",
   "send_scheduled_date": "2017-02-16T07:30:00Z",
   "targeting": {
      "message_template": "Test Broadcast SAT 2 {{ list_name }} Reply HELP for help, STOP to cancel-Msg&data rates may apply",
      "shorten_urls": true,
      "short_url_base": "http://vbs.cm/",
      "source_short_code": null,
      "source_lists": [
         "123",
         "124"
      ],
      "filters": [
         {
            "name":"favorite_sport",
            "selector":"any",
            "value":[
               "football",
               "baseball"
            ]
         },
         {
            "name": "first_name",
            "selector": "starts_with",
            "value": "Steven"
         },
         {
            "name": "subscription_date",
            "selector": "before",
            "value": [
               "2017-01-01"
            ]
         }
      ]
   }
}

Return JSON

The following returns the Broadcast entity after the update.

{
   "broadcast_id": "123456",
   "status": "scheduled",
   "url": "/companies/:company_key/broadcasts/:broadcast_id",
   "name": "Test Broadcast SAT 2",
   "send_scheduled_date": "2017-02-16T07:30:00Z",
   "targeting": {
      "message_template": "Test Broadcast SAT 2 {{ list_name }} Reply HELP for help, STOP to cancel-Msg&data rates may apply",
      "shorten_urls": true,
      "short_url_base": "http://vbs.cm/",
      "source_short_code": null,
      "source_lists": [
         "123",
         "124"
      ],
      "filters": [
         {
            "name": "favorite_sport",
            "selector": "any",
            "value": [
               "football",
               "baseball"
            ]
         },
         {
            "name": "first_name",
            "selector": "starts_with",
            "value": "Steven"
         },
         {
            "name": "subscription_date",
            "selector": "before",
            "value": [
               "2017-01-01"
            ]
         }
      ]
   },
   "created_at": "2017-02-11T18:58:53Z",
   "updated_at": "2017-02-11T19:58:53Z"
}
Notes:
  • A 404 - Not Found error will be returned if the Broadcast entity does not exist.
  • A 403 - Forbidden status code will be returned if the Broadcast status does not allow updates.

Cancel/Delete a Broadcast

The following will cancel an existing scheduled Broadcast specified by :broadcast_id, and prevent it from being sent.

DELETE /companies/:company_key/mobiledb/broadcasts/:broadcast_id

Once a Broadcast is canceled, it's status will be canceled and cannot be sent or updated.

Note: Cancel/Delete only works for Broadcasts with a specified status.

Request JSON

None.

Return JSON

{
   "id": 20,
   "company_id": "a12ab1c",
   "name": "Testing",
   "status": "deleted",
   "shorten_urls": true,
   "short_url_base": "http://aaa.aaa.cm/",
   "created_by": null,
   "created_by_application": null,
   "activity_type": "Broadcast",
   "activity_uid": "5w1432ff-1sd5-46a0-ai7e-cs6e2efa13q8",
   "test_broadcast": false,
   "source_short_code": null,
   "message_template": "Test message",
   "send_scheduled_date": "2017-09-13T05:30:00Z",
   "source_lists": [
     "/api/companies/12345/lists/1"
   ],
   "channel": "sms",
   "filters": [],
   "url": "/companies/:company_key/broadcasts/:broadcast_id",
   "created_at": "2017-05-23T16:47:02Z",
   "updated_at": "2017-05-23T16:47:55Z"
}


Notes:

A 404 - Not Found error will be returned if the Broadcast entity does not exist.

A 403 - Forbidden status code will be returned if the Broadcast cannot be canceled because it has already been sent.

  • No labels

1 Comment

  1. Can we update source lists to subscription_lists