IMPSCloud API

From PresenceWiki
Revision as of 18:18, 1 November 2011 by Mattpryor (Talk | contribs)

Jump to: navigation, search

IMPSCloud API

Introduction

This document describes the web services API for sending, receiving and querying messages via the Presence / IMPSCloud service.­­

Sending a fax or email message

In order to create and send an outgoing fax or email message, the following web service calls should be made:

  • CFCreateMessageWS – creates the new message and places it in a

pending state on the outgoing queue.

  • CFAddRecipientWS – must be called at least once in order to specify

a recipient for this message. Multiple recipients can be added be making successive calls. The recipient type will determine how the message is delivered, i.e. by fax or by email.

  • CFAddAttachmentWS – may be called zero or more times in order to

add an attachment file to the outgoing message (one per request). Note that attachments will be ignored for SMS messages.

  • CFSendMessageWS - finalizes and commits the outgoing message,

which will then be scheduled for delivery at the earliest opportunity.

After the message has been sent using CFSendMessageWS, its status can be monitored using the CFGetMessageStatusWS operation.

CFCreateMessageWS Operation

This Operation creates a new message and places it in a pending state on the outgoing queue. The message will not be ready for delivery until the CFSendFaxWS operation is called. Below is a list of elements that can be defined when making the call.

Request Elements

  • username [String]

This is your account username, which will be used for authentication purposes. This will be supplied by Presence. This element must appear exactly once.

  • password [String]

The password matching the username specified above. This element must appear exactly once.

  • clientMessageId [String]

This is a unique identifier specified by the client. The value will be stored against the message in the queue and can be used to identify it in subsequent calls. It will be echoed in the server response. This element can be omitted.

  • messageGroupId [String]

The MessageGroupId value identifies this message as belonging to a group of messages as defined by the client business logic. It can be used as a filter when retrieving the status of queued messages. This element can be omitted.

  • coverPage [String]

This specifies the name of the cover page to include with this message, if any. It can be omitted. Cover pages are in HTML format and must be installed separately using the CFInstallCoverPageWS operation (to be defined).

  • memo [String]

The memo field will be stored against the message in the queue and may be included in the fax coverpage using the $[COMMENTS] token.

  • messageBody [String]

The body text of the message, which will be the contents of an email message or the fax message. This can be HTML formatted, plain text or XML formatting instructions and can be omitted.

  • messageBodyType [String]

This specifies the format of the messageBody text, and the value can be either XML, HTML or TEXT. It is required if a messageBody element is included in the request.

  • messagePriority [Integer]

The value must be a number between 1 and 10 and specifies the priority of this message. 1 is the lowest priority and 10 is the highest.

  • resolution [String]

Specifies the resolution of the fax message if appropriate. Value may either be C (coarse) or F (fine).

  • sendTime [dateTime]

If included, the system will not attempt to deliver the message until after the specified date and time.

  • senderEmail [String]

For email messages this specifies the “from” address of the message.

  • senderName [String]

The name of the sender, which will be included in the cover page if present using the $[FROM] token.

  • senderNumber [String]

The originating fax number for fax messages. Will be included in the cover page if present using the $[SND_FAX#] token.

  • subject [String]

The subject of the message. The value can be included in the cover page if present using the $[SUBJECT] token.

  • bannerGFX [String]

Optional URL or UNC of a banner graphic that can be included. Please note that this feature is not supported for FAXCOM transmissions.

  • handlerTask [String]

This element designates a special Task to handle the formatting or any other special functionality. It can be omitted.

  • preferredPresenceServer [String]

This indicates that the message should be handled by a specified Presence server. It can be omitted.

Response Elements

  • clientMessageId [String]

This is identical to the clientMessageId specified in the request and is echoed here for convenience.

  • presenceUniqueIdentifier [String]

This is the auto­generated unique identifier for the message and can be used for subsequence requests pertaining to this message (as an alternative, or in addition to, the clientMessageId).

  • serverResponse [String]

A three digit response code followed by a colon ( : ) followed by a descriptive message. CloudFax Server Responses for further information (document in progress).

CFAddRecipientWS Operation

This Operation adds a recipient to an existing (queued) message. It can be called once or as many times as is required. IMPSCloud will attempt to send the message to each recipient specified by each call and the delivery format will depend on the recipient type.

Request Elements

  • clientMessageId [String]

This identifies the message to be updated and can be specified in the initial CFCreateMessageWS call. It can be provided as an alternative to the "presenceUniqueIdentifier" element.

  • presenceUniqueIdentifier [String]

This identifies the message to be updated and is specified in the response to the initial CFCreateMessageWS.

  • username [String]

This is your account username, which will be used for authentication purposes. This will be supplied by Presence. This element must appear exactly once.

  • password [String]

The password matching the username specified above. This element must appear exactly once.

  • recipientEmail [String]

This specifies the recipient’s email address and must be included if the recipientType element has a value of EMAIL. Messages to this recipient will be delivered in email format and attachment files will be included as MIME attachments.

  • recipientName [String]

The name of the recipient.

  • recipientPhone [String]

The telephone number of the fax machine that this message is to be delivered to. This will be ignored if the recipientType is not set to “FAX” or “SMS”.

  • recipientType [String]

The type of recipient to add (required). The value of this element can be FAX, SMS or EMAIL.

  • recipientEmailScope [String]

Defines the scope of this recipient, if EMAIL type is specified. May be TO, CC or BCC. If not specified, the scope will default to TO.

Response Elements

  • clientMessageId [String]

This is identical to the clientMessageId specified in the original CFCreateMessageWS request and is echoed here for convenience.

  • presenceUniqueIdentifier [String]

This is the auto­generated unique identifier for the message.

  • serverResponse [String]

A three digit response code followed by a colon ( : ) followed by a descriptive message. Please see CloudFax Server Responses for further information (document in progress).

  • recipientId [Integer]

This is the auto-­generated ID for this recipient.

CFAddAttachmentWS Operation

This Operation updates an existing message (created using CFCreateMessageWS) to add an attachment file. It can be called as many times as necessary for each attachment.

Request Elements

  • clientMessageId [String]

This identifies the message to be updated and can be specified in the initial CFCreateMessageWS call. It can be provided as an alternative to the “presenceUniqueIdentifier” element.

  • presenceUniqueIdentifier [String]

This identifies the message to be updated and is specified in the response to the initial CFCreateMessageWS.

  • username [String]

This is your account username, which will be used for authentication purposes. This will be supplied by Presence. This element must appear exactly once.

  • password [String]

The password matching the username specified above. This element must appear exactly once.

  • attachment_data [Base64Binary]

This is the base­64 encoded byte array that contains the contents of the attachment.

  • attachment_type [String]

The MIME type of the attachment, e.g. “Image/TIFF”.

  • attachment_name [String]

This element specifies the filename of the attachment.

Response Elements

  • clientMessageId [String]

This is identical to the clientMessageId specified in the original CFCreateMessageWS request and is echoed here for convenience.

  • presenceUniqueIdentifier [String]

This is the auto­generated unique identifier for the message.

  • serverResponse [String]

A three digit response code followed by a colon ( : ) followed by a descriptive message. Please see CloudFax Server Responses for further information (document in progress).

CFSendMessageWS Operation

This operation commits the message and makes it available for sending at the earliest opportunity. It should be the last call made after CFCreateMessageWS, CFAddRecipientWS and CFAddAttachmentWS.

Request Elements

  • clientMessageId [String]

This identifies the message to be sent and can be specified in the initial CFCreateMessageWS call. It can be provided as an alternative to the “presenceUniqueIdentifier” element.

  • presenceUniqueIdentifier [String]

This identifies the message to be sent and is specified in the response to the initial CFCreateMessageWS.

  • username [String]

This is your account username, which will be used for authentication purposes. This will be supplied by Presence. This element must appear exactly once.

  • password [String]

The password matching the username specified above. This element must appear exactly once.

Response Elements

  • clientMessageId [String]

This is identical to the clientMessageId specified in the original CFCreateMessageWS request and is echoed here for convenience.

  • presenceUniqueIdentifier [String]

This is the auto­generated unique identifier for the message.

  • serverResponse [String]

A three digit response code followed by a colon ( : ) followed by a descriptive message. Please see CloudFax Server Responses for further information (document in progress).