IMPSCloud API

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

(diff) ←Older revision | view current revision (diff) | Newer revision→ (diff)
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).

CFCancelMessageWS Operation

This operation cancels a previously created message. It may be called at any time after CFCreateMessageWS. Note that this operation may not be effective if a message has already been submitted for delivery.

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 cancelled and is specified in the response to the initial CFCreateMessageWS.

  • recipientId [String]

If present, this will only cancel messages bound to the specified destination. Other destinations will be unaffected.

  • 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).

CFGetMessageStatusWS Operation

This Operation queries the queue and returns the current status of a single outgoing message, including information about each individual recipient.

Request Elements

  • clientMessageId [String]

This identifies the message to be queried 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 queried 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).

  • messageStatus [String]

This describes the status of the overall message. It will be one of the following:

  • WAITING :­ The message has not yet been released with CFSendMessageWS
  • PENDING :­ The message has been released for delivery
  • IN_PROGRESS :­ The message is in the process of delivery.
  • CANCELLED :­ The message has been cancelled prior to sending
  • PARTIAL :­ The message was partially sent to one or more recipients – check individual recipient statuses for more information (see dataTableRow below).
  • GONE :­ The message delivery has completed.
  • FAILED :­ The message failed in its entirety.

8 pages [Integer] Specifies the number of pages in this message, if yet known. This will only be present if there is at least one FAX type recipient.

  • dataTableRow [ComplexType]

This element may appear zero or more times for each recipient added to the message. It contains one of each of the following child elements:

  • RECIPIENT_ID [Integer]

This is the unique identifier assigned to the recipient.

  • DELIVERY_STATUS [String]

This indicates the delivery status for this recipient and will be one of the following:

  • H=Held
  • W=Waiting (not yet released)
  • F=Failed
  • S=Sent
  • T=Timed/Scheduled resend
  • R=Relayed
  • B=Busy
  • P=Pending
  • N=Non­Busy retry
  • STATUS_DESCRIPTION [String]

If available, a detailed description of the delivery status.

  • RECIPIENT_EMAIL [String]

If this message is an “EMAIL” type, this will display the recipient’s email address.

  • RECIPIENT_PHONE [String]

If this message is a “FAX” type or an “SMS” type, this will display the recipient’s telephone number.

  • RECIPIENT_TYPE [String]

This returns the recipient type as specified in the original CFAddRecipientWS call, one of: FAX, EMAIL, SMS

  • NUMBER_ATTEMPTS [Integer]

This represents the number of attempts that have been made to send this message.

  • LAST_ATTEMPT [DateTime]

This specifies the date and time of the last attempt for this recipient.

  • NEXT_ATTEMPT [DateTime]

If known, this field specifies the next time the message delivery will be attempted.

CFListOutboundMessagesWS Operation

This operation returns a list of outbound messages and status information based on filter criteria provided in the request.

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.

  • groupIdFilter [String]

If specified, this will limit messages returned to those whose “groupId” matches the value of this node.

  • minimumSendDate [dateTime]

This node may occur zero or one times. If present, results returned will be limited to those that were sent on or after the date and time specified.

  • maximumSendDate [dateTime]

This node may occur zero or one times. If present, results returned will be limited to those that were sent on or before the date and time specified.

  • deliveryStatusFilter [String]

This node may occur zero or more times. If present results will be limited to those that match the specified delivery status.

  • restrictToChanged [Boolean]

If this element is present and has a true value, results will be restricted to those whose deliveryStatus has altered from the time of the previous query.

Response Elements

  • serverResponse [String]

A three digit response code followed by a colon ( : ) followed by a descriptive message. Please see http://www.internationalpresence.com/wikidocs/index.php? title=CloudFax_Server_Responses for further information (document in progress).

  • dataTableRow [ComplexType]

This element may appear zero or more times for each message and recipient. It contains one of each of the following child elements:

  • PRESENCE_UNIQUE_IDENTIFIER [String]

This is the unique identifier for this message as specified by the queue system. Note that one message may appear multiple times for each recipient added to the message.

  • CLIENT_UNIQUE_IDENTIFIER [String]

This is the unique identifier for this message as specified by the client. As with the PRESENCE_UNIQUE_IDENTIFIER, this may appear multiple times for each recipient.

  • GROUP_ID [String]

This is the GroupId field specified when the message was initially created.

  • MESSAGE_STATUS [String]

The status of this message (encompasses all recipients and is distinct from DELIVERY_STATUS which is distinct for each recipient). One of the following:

  • WAITING :­ The message has not yet been released with CFSendMessageWS
  • PENDING :­ The message has been released for delivery
  • IN_PROGRESS :­ The message is in the process of delivery.
  • CANCELLED :­ The message has been cancelled prior to sending
  • PARTIAL :­ The message was partially sent to one or more recipients – check individual recipient statuses for more information (see dataTableRow below).
  • GONE :­ The message delivery has completed.
  • FAILED :­ The message failed in its entirety.
  • RECIPIENT_ID [Integer]

This is the unique identifier for this recipient. It is equal to the recipientId value returned in the response to the CFAddRecipientWS operation.

  • DELIVERY_STATUS [String]

This indicates the delivery status for this recipient and will be one of the following:

  • H=Held
  • W=Waiting (not yet released)
  • F=Failed
  • S=Sent
  • T=Timed/Scheduled resend
  • R=Relayed
  • B=Busy
  • P=Pending
  • N=Non­Busy retry
  • RECIPIENT_EMAIL [String]

If this message is an “EMAIL” type, this will display the recipient’s email address.

  • RECIPIENT_PHONE [String]

If this message is a “FAX” type or an “SMS” type, this will display the recipient’s telephone number.

  • RECIPIENT_TYPE [String]

This returns the recipient type as specified in the original CFAddRecipientWS call, one of: FAX, EMAIL, SMS

  • NUMBER_ATTEMPTS [Integer]

This represents the number of attempts that have been made to send this message.

  • LAST_ATTEMPT [DateTime]

This specifies the date and time of the last attempt for this recipient.

  • NEXT_ATTEMPT [DateTime]

If this message is an “EMAIL” type, this will display the recipient’s email address.