Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API for Sending Messages - Revision history

Pankuma3: /* Schema */

2012-06-13T10:46:59Z

Schema

← Older revision		Revision as of 10:46, 13 June 2012
Line 145:		Line 145:

	Recipients for a message are identified in a recipient list. Each recipient has a recipient type and an address. The address information for an inbound message is filled out with any information that is available. Each address that is part of a recipient for an outbound message must contain an object identifier and a type, or a "blind" address in the SmtpAddress field.		Recipients for a message are identified in a recipient list. Each recipient has a recipient type and an address. The address information for an inbound message is filled out with any information that is available. Each address that is part of a recipient for an outbound message must contain an object identifier and a type, or a "blind" address in the SmtpAddress field.
		+	User needs to specify either an object identifier or DtmfAccessID or SmtpAddress in order to sendMessage to another user.

	The schema for recipients and addresses:		The schema for recipients and addresses:
Line 164:		Line 165:
	<xs:element name="UserGuid" type="xs:string" minOccurs="0" />		<xs:element name="UserGuid" type="xs:string" minOccurs="0" />
	<xs:element name="DisplayName" type="xs:string" minOccurs="0" />		<xs:element name="DisplayName" type="xs:string" minOccurs="0" />
-	<xs:element name="SmtpAddress" type="xs:string" minOccurs="0" />	+	<xs:element name="SmtpAddress" type="xs:string" minOccurs="0" />
		+	<xs:element name="DtmfAccessID" type="xs:string" minOccurs="0" />
	</xs:all>		</xs:all>
	</xs:complexType>		</xs:complexType>
Line 196:		Line 198:

	Container objects are simply attachments and recipients.		Container objects are simply attachments and recipients.
-

	== Addressing ==		== Addressing ==

Anilve at 06:59, 1 March 2012

2012-03-01T06:59:39Z

← Older revision		Revision as of 06:59, 1 March 2012
Line 269:		Line 269:
	</pre>		</pre>

		+
		+	----
		+
		+	{\| border="1" class="wikitable"
		+	\|-
		+	! style="background-color: rgb(255, 215, 0);" \| '''Back to:''' [[Cisco Unity Connection Messaging Interface (CUMI) API\|CUMI API Overview ]]
		+	\|}

	[[Category:Cisco Unity Connection Messaging Interface (CUMI) API]]		[[Category:Cisco Unity Connection Messaging Interface (CUMI) API]]

Anilve at 06:59, 1 March 2012

2012-03-01T06:59:02Z

← Older revision		Revision as of 06:59, 1 March 2012
Line 1:		Line 1:
-	~~'''Links to Other API pages:''' [[Cisco_Unity_Connection_APIs]]~~	+	{\| border="1" class="wikitable"
-	{\| ~~align="right"~~ border="1"	+
-	~~\|align~~="~~center~~"~~\|'''CUMI Guide Contents'''~~	+
	\|-		\|-
-	~~\|[[Cisco Unity Connection Messaging Interface (CUMI) API\|API Overview ]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API~~ -~~- Using the CUMI API\|Using the CUMI API for Mailboxes & Folders]]<br>[[Cisco Unity Connection Messaging Interface~~ (~~CUMI~~) ~~API -- Using the CUMI API for Sending Messages~~\|~~Using the CUMI API for Sending Messages]]<br>~~[[Cisco Unity Connection Messaging Interface (CUMI) API ~~-- Using the CUMI API for Sending Notifications~~\|~~Using the~~ CUMI API for Sending Notifications]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API for Broadcast Messages\|Using the CUMI API for Broadcast Messages]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- HTTP Samples\|HTTP Samples]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Sending a Voice Message with One or More Attachments\|Sending a Voice Message with One or More Attachments]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Preventing Messages from Being Automatically Deleted (Investigative Hold)\|Preventing Messages from Being Deleted (Investigative Hold)]]	+	! style="background-color: rgb(255, 215, 0);" \| '''Back to:''' [[Cisco Unity Connection Messaging Interface (CUMI) API\|CUMI API Overview ]]
	\|}		\|}

Anilve at 23:34, 24 February 2012

2012-02-24T23:34:19Z

← Older revision		Revision as of 23:34, 24 February 2012
Line 3:		Line 3:
	\|align="center"\|'''CUMI Guide Contents'''		\|align="center"\|'''CUMI Guide Contents'''
	\|-		\|-
-	\|[[Cisco Unity Connection Messaging Interface (CUMI) API\|API Overview ]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API\|Using the CUMI API ]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API for Sending Messages\|Using the CUMI API for Sending Messages]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API for Sending Notifications\|Using the CUMI API for Sending Notifications]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API for Broadcast Messages\|Using the CUMI API for Broadcast Messages]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- HTTP Samples\|HTTP Samples]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Sending a Voice Message with One or More Attachments\|Sending a Voice Message with One or More Attachments]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Preventing Messages from Being Automatically Deleted (Investigative Hold)\|Preventing Messages from Being Deleted (Investigative Hold)]]	+	\|[[Cisco Unity Connection Messaging Interface (CUMI) API\|API Overview ]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API\|Using the CUMI API for Mailboxes & Folders]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API for Sending Messages\|Using the CUMI API for Sending Messages]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API for Sending Notifications\|Using the CUMI API for Sending Notifications]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API for Broadcast Messages\|Using the CUMI API for Broadcast Messages]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- HTTP Samples\|HTTP Samples]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Sending a Voice Message with One or More Attachments\|Sending a Voice Message with One or More Attachments]]<br>[[Cisco Unity Connection Messaging Interface (CUMI) API -- Preventing Messages from Being Automatically Deleted (Investigative Hold)\|Preventing Messages from Being Deleted (Investigative Hold)]]
	\|}		\|}

Gscorbin: 1 revision

2010-12-13T23:57:07Z

1 revision

← Older revision

Revision as of 23:57, 13 December 2010

Gscorbin at 22:57, 13 December 2010

2010-12-13T22:57:21Z

New page

'''Links to Other API pages:''' [[Cisco_Unity_Connection_APIs]]
{| align="right" border="1"
|align="center"|'''CUMI Guide Contents'''
|-
|[[Cisco Unity Connection Messaging Interface (CUMI) API|API Overview ]] [[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API|Using the CUMI API ]] [[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API for Sending Messages|Using the CUMI API for Sending Messages]] [[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API for Sending Notifications|Using the CUMI API for Sending Notifications]] [[Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API for Broadcast Messages|Using the CUMI API for Broadcast Messages]] [[Cisco Unity Connection Messaging Interface (CUMI) API -- HTTP Samples|HTTP Samples]] [[Cisco Unity Connection Messaging Interface (CUMI) API -- Sending a Voice Message with One or More Attachments|Sending a Voice Message with One or More Attachments]] [[Cisco Unity Connection Messaging Interface (CUMI) API -- Preventing Messages from Being Automatically Deleted (Investigative Hold)|Preventing Messages from Being Deleted (Investigative Hold)]]
|}

__TOC__

== About Messages ==

A Message resource is what you might think of as a message "header" or "envelope." It is a small description of the message (from, to, time, etc.), so that loading a list of messages is efficient; the actual message content is provided in the form of links to one or more attachments.

There is no fixed limit on the number of recipients a message can have. Therefore, the recipient list is also provided as a link to an attachment; because there is no limit on the number of recipients, loading recipients into the Message resource could have a big impact on performance.

Non-delivery receipts (NDRs) have one additional child resource, FailedRecipients, which includes a Recipient URI and a failure status code.

== Sending Messages ==

A message can be sent by a POST request to the root URI for messages. The content of the request is "mutipart/form-data". There must be three pieces of data in the request in the following order:

# a message in either "application/xml" or "application/json" format
# a list of recipients
# audio data as "audio/wav" (optional, as a message can be sent with no audio)

=== Schema ===

<pre>
<xs:simpleType name="priorityType">
<xs:restriction base="xs:string">
<xs:enumeration value="Low" />
<xs:enumeration value="Normal" />
<xs:enumeration value="Urgent" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="sensitivityType">
<xs:restriction base="xs:string">
<xs:enumeration value="Normal" />
<xs:enumeration value="Personal" />
<xs:enumeration value="Private" />
<xs:enumeration value="Confidential" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="callerIdType">
<xs:all>
<xs:element name="CallerNumber" type="xs:string" />
<xs:element name="CallerName" type="xs:string" />
<xs:element name="CallerImage" type="xs:anyURI" />
</xs:all>
</xs:complexType>
<xs:simpleType name="messageType">
<xs:restriction base="xs:string">
<xs:enumeration value="Email" />
<xs:enumeration value="DR" />
<xs:enumeration value="Voice" />
<xs:enumeration value="RR" />
<xs:enumeration value="Fax" />
<xs:enumeration value="NDR" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="Message">
<xs:all>

<xs:element name="Subject" type="xs:string" minOccurs="0" />
<xs:element name="Read" type="xs:boolean" minOccurs="0" />

<xs:element name="Dispatch" type="xs:boolean" minOccurs="0" />
<xs:element name="Secure" type="xs:boolean" minOccurs="0" />
<xs:element name="Priority" type="priorityType" minOccurs="0" />
<xs:element name="Sensitivity" type="sensitivityType" minOccurs="0" />
<xs:element name="ReadReceiptRequested" type="xs:boolean" minOccurs="0" />
<xs:element name="DeliveryReceiptRequested" type="xs:boolean" minOccurs="0" />

<xs:element name="Attachments" type="Attachments" minOccurs="0" />
<xs:element name="Recipients" type="Recipients" minOccurs="0" />

<xs:element name="URI" type="xs:anyURI" />
<xs:element name="MsgId" type="xs:string" />
<xs:element name="From" type="Address" />
<xs:element name="CallerId" type="callerIdType" />
<xs:element name="ArrivalTime" type="xs:long" />
<xs:element name="Size" type="xs:unsignedLong" />
<xs:element name="Duration" type="xs:unsignedLong" />
<xs:element name="IMAPUid" type="xs:string" />
<xs:element name="FromSub" type="xs:boolean" />
<xs:element name="FromVmIntSub" type="xs:boolean" />
<xs:element name="Flagged" type="xs:boolean" minOccurs="0" />
<xs:element name="MsgType" type="messageType" minOccurs="0" />
<xs:element name="ModificationTime" type="xs:long" minOccurs="0" />
<xs:element name="IsDraft" type="xs:boolean" minOccurs="0" />
<xs:element name="IsDeleted" type="xs:long" minOccurs="0" />
<xs:element name="IsSent" type="xs:long" minOccurs="0" />
<xs:element name="IsFuture" type="xs:long" minOccurs="0" />
<xs:element name="FolderURI" type="xs:anyURI" minOccurs="0" />
</xs:all>
</xs:complexType>
<xs:element name="Message" type="Message" />
<xs:element name="Messages">
<xs:complexType>
<xs:sequence>
<xs:element name="Message" type="Message" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
</pre>

When sending a message, the following fields can be set:

* dispatch
* secure
* priority
* sensitivity
* read receipt requested
* delivery receipt requested

On a received message, the following fields can be modified:

* priority
* subject
* read

Although a message can appear in a folder, it is always available via a unique id:

<pre>
/vmrest/mailbox/messageid
</pre>

Because messages include attachments and recipients that are not efficiently included in the envelope of the message, they are filled out only when an individual message is requested.

The following is the resource definition for attachments and recipients:

<pre>
<xs:complexType name="Attachment">
<xs:all>
<xs:element name="URI" type="xs:anyURI" />
</xs:all>
</xs:complexType>
<xs:element name="Attachment" type="Attachment" />
<xs:complexType name="Attachments">
<xs:sequence>
<xs:element name="Attachment" type="Attachment" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</pre>

Recipients for a message are identified in a recipient list. Each recipient has a recipient type and an address. The address information for an inbound message is filled out with any information that is available. Each address that is part of a recipient for an outbound message must contain an object identifier and a type, or a "blind" address in the SmtpAddress field.

The schema for recipients and addresses:

<pre>
<xs:simpleType name="addressType">
<xs:restriction base="xs:string">
<xs:enumeration value="SUBSCRIBER" />
<xs:enumeration value="DISTRIBUTIONLIST" />
<xs:enumeration value="PRIVATELIST" />
<xs:enumeration value="CONTACT" />
<xs:enumeration value="VPIMCONTACT" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="Address">
<xs:all>
<xs:element name="ObjectId" type="xs:string" minOccurs="0" />
<xs:element name="Type" type="addressType" minOccurs="0" />
<xs:element name="UserGuid" type="xs:string" minOccurs="0" />
<xs:element name="DisplayName" type="xs:string" minOccurs="0" />
<xs:element name="SmtpAddress" type="xs:string" minOccurs="0" />
</xs:all>
</xs:complexType>
<xs:element name="Address" type="Address" />
<xs:complexType name="Addresses">
<xs:sequence>
<xs:element name="Address" type="Address" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:element name="Addresses" type="Addresses" />
<xs:simpleType name="recipientType">
<xs:restriction base="xs:string">
<xs:enumeration value="TO" />
<xs:enumeration value="CC" />
<xs:enumeration value="BCC" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="Recipient">
<xs:all>
<xs:element name="Type" type="recipientType" />
<xs:element name="Address" type="Address" />
</xs:all>
</xs:complexType>
<xs:element name="Recipient" type="Recipient" />
<xs:complexType name="Recipients">
<xs:sequence>
<xs:element name="Recipient" type="Recipient" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</pre>

Container objects are simply attachments and recipients.

== Addressing ==

Addressing in CUMI consists of a lookup method that returns a list of addresses matching a specified name or the beginning of a name:

{| border="1" cellspacing="0" cellpadding="5" align="center"
! URI
! Request
! Description
|-
| /mailbox/addresses?name=<full or partial name>
| GET
| Returns an Address resource that lists all of the matched names (up to a maximum of 100).
|}

The name can be a whole name, or the beginning of the first name, last name, display name, or alias. The name value in the URI will match distribution lists, personal distribution lists, contacts, and users.

For example, when searching for the user "Alexander Bell," the name could be any of the following:

<pre>
name=abell
name=alexander
name=alex
name=bell
name=bel
name=alexander be
name=alex be
</pre>

== Error Handling ==

When errors are encountered on the server, the CUMI API adheres to the standard REST practice of using the closest HTTP code available. It also follows the recommendation in "RESTful Web Services," and returns an error document that is human readable (and also program readable).

The approach is to return codes in descending order: first the HTTP code, then the relevant VMWS error if possible, and finally the original error code and message. We generally have two levels of errors in this particular case, but the errors will be a general list to provide a more extensible mechanism.

For example:

<pre>
403 Forbidden
Content-Type: application/xml
Date: Fri, 10 Nov 2008 20:04:45 GMT
Server: UnityConnection
Transfer-Encoding: chunked
<?xml version="1.0" encoding="UTF-8"?>
<Error>
<Code>E_VMWS_MSG_MAILBOX_FULL</Code>
<Message>Destination mailbox is full or send quota was exceeded.</Message>
<Code>0x80046408</Code>
<Message>E_CML_SEND_QUOTA_EXCEEDED</Message></Error>
</pre>

The VMWS error codes are intended to make it easier for Cannonball and Midlet clients to cut over to this interface. In addition, having a code between HTTP and the lowest-level component error code is useful. New VMWS errors that do not apply to the SOAP interface are added in the form "E_VM{_}REST_\_<new-error>".

Here's the XSD snippet for a RestError:

<pre>
<xs:element name="RestError">
<xs:complexType>
<xs:all>
<xs:element name="error" maxOccurs="unbounded">
<xs:complexType>
<xs:all>
<xs:element name="code" type="ErrorCode"/>
<xs:element name="message" type="xs:string"/>
</xs:all>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType></xs:element>
</pre>

[[Category:Cisco Unity Connection Messaging Interface (CUMI) API]]