/messages/voice

Use this resource to list and create Voice messages.

Secured By: Authentication Token
Description:

List Voice messages.

Responses with more than 50 records will be paginated to 50 records per response, unless otherwise specified.

Headers

Name Required Type Description
X-AUTH-TOKEN * string

An authentication token provided to you by GovDelivery.

Status

Headers

Name Type Description
Link string

Appropriate pagination link relations. Can include “first”, “last”, “prev”, and “next” relations.

Example

< /messages/voice?page=1>; rel="first",
< /messages/voice?page=2>; rel="prev",
< /messages/voice?page=4>; rel="next",
< /messages/voice?page=5>; rel="last"

Body

Format: application/json

Example
[
  {
    "say_text": "Test Message!",
    "completed_at": "2012-10-30T16:26:22Z",
    "created_at": "2012-10-30T16:26:19Z",
    "status": "completed",
    "_links": {
      "self": "/messages/voice/64",
      "recipients": "/messages/voice/64/recipients",
      "failed": "/messages/voice/64/recipients/failed",
      "sent": "/messages/voice/64/recipients/sent"
    }
  },
  {
    "play_url": "http://www.example.com/media/hello.wav",
    "created_at": "2014-10-07T17:27:12Z",
    "completed_at": "2014-10-07T17:32:51Z",
    "status": "completed",
    "_links": {
      "self": "/messages/voice/153",
      "recipients": "/messages/voice/153/recipients",
      "failed": "/messages/voice/153/recipients/failed",
      "sent": "/messages/voice/153/recipients/sent"
    }
  }
]
Schema
Array of objects that may include:
Name Type Description
play_url string

Audio file to play when the recipient receives the voice message. Must be present if say_text is not present.

Example

https://ia902508.us.archive.org/5/items/testmp3testfile/mpthreetest.mp3
say_text string

Text to synthesize and speak when the recipient receives the voice message. Must be present if play_url is not present.

Example

Hello, this is a test of sending a voice message. Good bye.
created_at string

The date and time when the message was created.

Example

2013-01-30T17:45:27Z
_links object

An object that defines links to related objects.

Properties

{
  "self": {
    "description": "Relative URI of the object",
    "type": "string",
    "example": "/messages/voice/10040"
  },
  "recipients": {
    "description": "Relative URI to the list of recipients of the message",
    "type": "string",
    "example": "/messages/voice/10040/recipients"
  },
  "failed": {
    "description": "Relative URI to the list of recipients that have failed to receive the message",
    "type": "string",
    "example": "/messages/voice/10040/recipients/failed"
  },
  "sent": {
    "description": "Relative URI to the list of recipients that have been successfully received the message",
    "type": "string",
    "example": "/messages/voice/10040/recipients/sent"
  },
  "human": {
    "type": "string",
    "example": "/messages/voice/10040/recipients/human"
  },
  "machine": {
    "type": "string",
    "example": "/messages/voice/10040/recipients/machine"
  },
  "busy": {
    "type": "string",
    "example": "/messages/voice/10040/recipients/busy"
  },
  "no_answer": {
    "type": "string",
    "example": "/messages/voice/10040/recipients/no_answer"
  },
  "could_not_connect": {
    "type": "string",
    "example": "/messages/voice/10040/recipients/could_not_connect"
  }
}
status string

new - message has been created

queued - message has been queued for sending

sending - message has begun sending

completed - all recipients have positive confirmation or have expired

Valid Values:

  • new
  • queued
  • sending
  • completed

Example

completed
 
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Voice Messages",
  "description": "A List of voice messages you have sent.",
  "type": "array",
  "items": {
    "title": "Voice Message",
    "type": "object",
    "properties": {
      "play_url": {
        "description": "Audio file to play when the recipient receives the voice message. Must be present if say_text is not present.",
        "type": "string",
        "example": "https://ia902508.us.archive.org/5/items/testmp3testfile/mpthreetest.mp3"
      },
      "say_text": {
        "description": "Text to synthesize and speak when the recipient receives the voice message. Must be present if play_url is not present.",
        "type": "string",
        "example": "Hello, this is a test of sending a voice message. Good bye."
      },
      "created_at": {
        "description": "The date and time when the message was created.",
        "type": "string",
        "example": "2013-01-30T17:45:27Z"
      },
      "_links": {
        "title": "Relational Links",
        "description": "An object that defines links to related objects.",
        "type": "object",
        "properties": {
          "self": {
            "description": "Relative URI of the object",
            "type": "string",
            "example": "/messages/voice/10040"
          },
          "recipients": {
            "description": "Relative URI to the list of recipients of the message",
            "type": "string",
            "example": "/messages/voice/10040/recipients"
          },
          "failed": {
            "description": "Relative URI to the list of recipients that have failed to receive the message",
            "type": "string",
            "example": "/messages/voice/10040/recipients/failed"
          },
          "sent": {
            "description": "Relative URI to the list of recipients that have been successfully received the message",
            "type": "string",
            "example": "/messages/voice/10040/recipients/sent"
          },
          "human": {
            "type": "string",
            "example": "/messages/voice/10040/recipients/human"
          },
          "machine": {
            "type": "string",
            "example": "/messages/voice/10040/recipients/machine"
          },
          "busy": {
            "type": "string",
            "example": "/messages/voice/10040/recipients/busy"
          },
          "no_answer": {
            "type": "string",
            "example": "/messages/voice/10040/recipients/no_answer"
          },
          "could_not_connect": {
            "type": "string",
            "example": "/messages/voice/10040/recipients/could_not_connect"
          }
        }
      },
      "status": {
        "description": "new - message has been created\n\nqueued - message has been queued for sending\n\nsending - message has begun sending\n\ncompleted - all recipients have positive confirmation or have expired",
        "type": "string",
        "enum": [
          "new",
          "queued",
          "sending",
          "completed"
        ],
        "example": "completed"
      }
    }
  }
}

Body

Format: application/json

Example
{
  "error": "Invalid authentication token"
}
Secured By: Authentication Token
Description:

Creates a new Voice message. Request must include either play_url or say_text.

Headers

Name Required Type Description
X-AUTH-TOKEN * string

An authentication token provided to you by GovDelivery.

Body

Format: application/x-www-form-urlencoded

Form Parameters
Name Required Type Description
play_url string

URL of the audio media to play during the call.

Example

http://www.example.com/media/hello.wav
say_text string

Text to have spoken during the call.

Example

Hello
recipients * string

List of objects defining who will receive the call. Objects must include a “phone” attribute.

Example

[
    {
      "phone": "6515551000"
    },
    {
      "phone": "(651) 555-1001"
    }
]
Example
{
  "play_url": "http://www.example.com/media/hello.wav",
  "recipients": [
    {
      "phone": "6515551000"
    },
    {
      "phone": "(651) 555-1001"
    }
  ]
}
Schema
Object that may include:
Name Required Type Description
play_url string

URL of the audio media to play during the call.

Example

http://www.example.com/media/hello.wav
say_text string

Text to have spoken during the call.

Example

Hello
recipients * string

List of objects defining who will receive the call. Objects must include a “phone” attribute.

Example

[
    {
      "phone": "6515551000"
    },
    {
      "phone": "(651) 555-1001"
    }
]

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "/messages/voice",
  "description": "Creates a new Voice message. Request must include either play_url or say_text.",
  "type": "object",
  "properties": {
    "play_url": {
      "description": "URL of the audio media to play during the call.",
      "type": "string",
      "example": "http://www.example.com/media/hello.wav"
    },
    "say_text": {
      "description": "Text to have spoken during the call.",
      "type": "string",
      "example": "Hello"
    },
    "recipients": {
      "description": "List of objects defining who will receive the call. Objects\nmust include a \"phone\" attribute.\n",
      "type": "string",
      "example": "[\n    {\n      \"phone\": \"6515551000\"\n    },\n    {\n      \"phone\": \"(651) 555-1001\"\n    }\n]\n"
    }
  },
  "required": [
    "recipients"
  ]
}

Status

Body

Format: application/json

Example
{
  "play_url": "http://www.example.com/media/hello.wav",
  "recipient_detail_counts": {
    "busy": 0,
    "no_answer": 0,
    "human": 0,
    "machine": 1
  },
  "from_number": "+15551234567",
  "created_at": "2014-10-07T17:27:12Z",
  "completed_at": "2014-10-07T17:32:51Z",
  "status": "completed",
  "_links": {
    "self": "/messages/voice/153",
    "recipients": "/messages/voice/153/recipients",
    "failed": "/messages/voice/153/recipients/failed",
    "sent": "/messages/voice/153/recipients/sent",
    "human": "/messages/voice/15282/recipients/human",
    "machine": "/messages/voice/15282/recipients/machine",
    "busy": "/messages/voice/15282/recipients/busy",
    "no_answer": "/messages/voice/15282/recipients/no_answer",
    "could_not_connect": "/messages/voice/15282/recipients/could_not_connect"
  },
  "recipient_counts": {
    "total": 2,
    "new": 0,
    "sending": 0,
    "inconclusive": 0,
    "blacklisted": 0,
    "canceled": 0,
    "sent": 2,
    "failed": 0
  }
}
Description

Unprocessable Entity

Body

Format: application/json

Example
{
  "play_url": null,
  "recipient_detail_counts": {
    "busy": 0
    "no_answer": 0
    "human": 0
    "machine": 0
  },
  "from_number": "+15551234567",
  "created_at": null,
  "status": "new",
  "_links": {
    "self": "/messages/voice"
  },
  "errors": {
    "play_url": [
      "can't be blank"
    ],
    "say_text": [
      "can't be blank"
    ]
  }
}

Body

Format: application/json

Example
{
  "error": "Invalid authentication token"
}