Difference between revisions of "IMPSCloud"

From PresenceWiki
Jump to: navigation, search
(MESSAGE_STATUS)
 
(30 intermediate revisions by the same user not shown)
Line 9: Line 9:
 
http://www.international-presence.com/wikidocs/images/soap_architecture_2.png
 
http://www.international-presence.com/wikidocs/images/soap_architecture_2.png
  
Calls to IMPSCloud are made via the following SOAP operations:
+
== Standard call procedure ==
  
 +
=== Sending a fax or email message ===
  
* CFCreateMessageWS
+
In order to create and send an outgoing fax or email message, the following web service calls should be made:
* CFAddRecipientWS
+
* CFAddAttachmentWS
+
* CFSendMessageWS
+
* CFCancelMessageWS
+
* CFHoldMessageWS
+
* CFResendMessageWS
+
* CFReleaseMessageWS
+
* CFGetMessageStatusWS
+
* CFListOutboundMessagesWS
+
* CFListInboundMessagesWS
+
* CFRetrieveInboundAttachmentsWS
+
* CFDeleteMessageWS
+
* CFUploadCoverpageWS
+
  
== Operation Details ==
+
# [[#CFCreateMessageWS|CFCreateMessageWS]] – (required) creates the new message and places it in a Waiting state on the outgoing queue.
 +
# [[#CFAddRecipientWS|CFAddRecipientWS]] – (required) 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|CFAddAttachmentWS]] – (optional) 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. Attachments do not need to be included if the body of the message is included in the CFCreateMessageWS request.
 +
# [[#CFSendMessageWS|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|CFGetMessageStatusWS]] operation.
 +
 
 +
== SOAP Operations ==
 +
 
 +
Please note that the WSDL is located at:
 +
 
 +
http://www.international-presence.com/impscloud/impscloud.wsdl
  
 
=== CFCreateMessageWS ===
 
=== CFCreateMessageWS ===
Line 41: Line 40:
 
This is your account username, which will be used for authentication purposes. This will be supplied by Presence. This element must appear exactly once.
 
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 ====
+
===== password =====
 
String
 
String
  
 
The password matching the username specified above. This element must appear exactly once.
 
The password matching the username specified above. This element must appear exactly once.
  
==== clientMessageId ====
+
===== clientMessageId =====
 
String
 
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.
 
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 ====
+
===== messageGroupId =====
 
String
 
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.
 
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 ====
+
===== coverPage =====
 
String
 
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).
 
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 ====
+
===== memo =====
 
String
 
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.
 
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 ====
+
===== messageBody =====
 
String
 
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 for creating a PDF file – this can be omitted.
 
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 for creating a PDF file – this can be omitted.
  
==== messageBodyType ====
+
===== messageBodyType =====
 
String
 
String
  
 
This specifies the format of the messageBody text, and the value can be either PDF, HTML or TEXT. It is required if a messageBody element is included in the request.
 
This specifies the format of the messageBody text, and the value can be either PDF, HTML or TEXT. It is required if a messageBody element is included in the request.
  
==== messagePriority ====
+
===== messagePriority =====
 
Integer
 
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.
 
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 ====
+
===== resolution =====
 
String
 
String
  
 
Specifies the resolution of the fax message if appropriate. Value may either be C (coarse) or F (fine).
 
Specifies the resolution of the fax message if appropriate. Value may either be C (coarse) or F (fine).
  
==== sendTime ====
+
===== sendTime =====
 
dateTime
 
dateTime
  
 
If included, the system will not attempt to deliver the message until after the specified date and time.
 
If included, the system will not attempt to deliver the message until after the specified date and time.
  
==== senderEmail ====
+
===== senderEmail =====
 
String
 
String
  
 
For email messages this specifies the “from” address of the message.
 
For email messages this specifies the “from” address of the message.
  
==== senderName ====
+
===== senderName =====
 
String
 
String
  
 
The name of the sender, which will be included in the cover page if present using the $[FROM] token.
 
The name of the sender, which will be included in the cover page if present using the $[FROM] token.
  
==== senderNumber ====
+
===== senderNumber =====
 
String
 
String
  
 
The originating fax number for fax messages. Will be included in the cover page if present using the $[SND_FAX#] token.
 
The originating fax number for fax messages. Will be included in the cover page if present using the $[SND_FAX#] token.
  
==== subject ====
+
===== subject =====
 
String
 
String
  
 
The subject of the message. The value can be included in the cover page if present using the $[SUBJECT] token.
 
The subject of the message. The value can be included in the cover page if present using the $[SUBJECT] token.
  
==== preferredPresenceServer ====
+
===== preferredPresenceServer =====
 
String
 
String
  
 
This indicates that a specified Presence server should handle the message. It can be omitted.
 
This indicates that a specified Presence server should handle the message. It can be omitted.
  
=== Response Elements ===
+
==== Response Elements ====
  
====clientMessageId====
+
=====clientMessageId=====
 
String
 
String
  
 
This is identical to the clientMessageId specified in the request and is echoed here for convenience.
 
This is identical to the clientMessageId specified in the request and is echoed here for convenience.
  
====presenceUniqueIdentifier====
+
=====presenceUniqueIdentifier=====
 
String
 
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).
 
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====
+
=====serverResponse=====
 
String
 
String
  
Line 257: Line 256:
 
   
 
   
  
Response Elements
+
==== Response Elements====
  
 
=====clientMessageId=====
 
=====clientMessageId=====
Line 276: Line 275:
  
 
=== CFSendMessageWS ===
 
=== CFSendMessageWS ===
 +
 +
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 http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).
  
 
=== CFCancelMessageWS ===
 
=== CFCancelMessageWS ===
 +
 +
This operation requests that a previously created message is cancelled. It may be called at any time after CFCreateMessageWS. Note that this operation may not be effective if a message has already been relayed.
 +
 +
====Request Elements====
 +
 +
=====clientMessageId=====
 +
String
 +
 +
This identifies the message to be cancelled 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 http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).
  
 
=== CFHoldMessageWS ===
 
=== CFHoldMessageWS ===
 +
 +
This Operation requests that the specified message is held. This Operation does not guarantee that a message is held as a message may already be in the process of delivery. To release the message at a later date call the CFReleaseMessageWS Operation.
 +
 +
==== Request Elements ====
 +
 +
===== clientMessageId=====
 +
String
 +
 +
This identifies the message to be held 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 held and is specified in the response to the initial CFCreateMessageWS.
 +
 +
=====recipientId=====
 +
String
 +
 +
If a message has multiple recipients, this can be used to specify a single recipient. If all messages to all recipients are to be held, use presenceUniqueIdentifier or clientMessageId.
 +
 +
=====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 http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).
  
 
=== CFResendMessageWS ===
 
=== CFResendMessageWS ===
 +
 +
This Operation requests that the specified message is resent. If the message is not in a “Sent” or “Cancelled” state, the request will be rejected.
 +
 +
====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.
 +
 +
=====recipientId=====
 +
String
 +
 +
If a message has multiple recipients, this can be used to specify a single recipient. If all messages to all recipients are to be held, use presenceUniqueIdentifier or clientMessageId.
 +
 +
=====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.
 +
 +
=====resendAfterDateTime=====
 +
String
 +
 +
Optional. If present, the system will not attempt to resend the message until after the specified date and time.
 +
 +
====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 http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).
  
 
=== CFReleaseMessageWS ===
 
=== CFReleaseMessageWS ===
 +
 +
This Operation requests that the specified message is released. This can only be called on messages that are currently in a “Held” state.
 +
 +
====Request Elements====
 +
 +
=====clientMessageId=====
 +
String
 +
 +
This identifies the message to be released 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 released and is specified in the response to the initial CFCreateMessageWS.
 +
 +
=====recipientId=====
 +
String
 +
 +
If a message has multiple recipients, this can be used to specify a single recipient. If all recipients are to be released, use presenceUniqueIdentifier or clientMessageId.
 +
 +
=====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 http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).
  
 
=== CFGetMessageStatusWS ===
 
=== CFGetMessageStatusWS ===
 +
 +
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 http://www.international-presence.com/wikidocs/index.php?title=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 ( W ) :- The message has not yet been released with CFSendMessageWS
 +
*PENDING ( P ) :- The message has been released for delivery
 +
*RELAYED ( R ):- The message is in the process of delivery.
 +
*CANCELLED ( C ):- The message has been cancelled prior to sending
 +
*PARTIAL ( L ) :- The message was partially sent to one or more recipients – check individual recipient statuses for more information (see dataTableRow below).
 +
*SENT ( S ):- The message delivery has completed.
 +
*FAILED ( F ):- The message failed in its entirety.
 +
 +
=====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 ===
 
=== CFListOutboundMessagesWS ===
 +
 +
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. Please use the single character abbreviation specified above.
 +
 +
=====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.international-presence.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
 +
RELAYED :- 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).
 +
SENT :- 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.
  
 
=== CFListInboundMessagesWS ===
 
=== CFListInboundMessagesWS ===
 +
 +
This Operation returns a filtered list of inbound messages.
 +
 +
====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.
 +
 +
=====minimumReceivedDate=====
 +
DateTime
 +
 +
This element may appear once or zero times. If present, messages returned will be limited to those that were received on or after the date specified.
 +
 +
======maximumReceivedDate======
 +
dateTime
 +
 +
This element may appear once or zero times. If present, messages returned will be limited to those that were received on or after the date specified.
 +
 +
=====messageTypeFilter=====
 +
String
 +
 +
If present, messages will be limited to the type specified, which may be one of:
 +
 +
*FAX
 +
*EMAIL
 +
*SMS
 +
 +
=====destinationFilter=====
 +
String
 +
 +
If present, messages will be limited to those with the intended destination. Destination can include the asterisk (*) character as a wildcard.
 +
 +
=====originatorFilter=====
 +
String
 +
 +
If present, messages will be limited to those with the specified originator number or address. Originator string can include the asterisk (*) character as a wildcard.
 +
 +
=====messageTag1Filter=====
 +
String
 +
 +
If a tagging mechanism has been set up for incoming messages (such as OCR), this can be used to filter the messages returned by the appropriate tag.
 +
 +
=====messageTag2Filter=====
 +
String
 +
 +
If a tagging mechanism has been set up for incoming messages (such as OCR), this can be used to filter the messages returned by the appropriate tag.
 +
 +
=====messageTag3Filter=====
 +
String
 +
 +
If a tagging mechanism has been set up for incoming messages (such as OCR), this can be used to filter the messages returned by the appropriate tag.
 +
 +
=====restrictToNewMessages=====
 +
Boolean
 +
 +
If true, only messages that have not previously been reported will be listed. Once a message has been listed using this operation it will be marked as reported and will not appear in future lists where this value is set to True.
 +
 +
====Response Elements====
 +
 +
=====serverResponse=====
 +
String
 +
 +
A three digit response code followed by a colon ( : ) followed by a descriptive message. Please see http://www.international-presence.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
 +
 +
The unique identifier assigned to this message on receipt
 +
 +
=====MESSAGE_TYPE=====
 +
String
 +
 +
The type of message. May be one of: FAX, EMAIL, SMS.
 +
 +
=====SUBJECT=====
 +
String
 +
 +
The subject line of the message, if present (usually this will only apply to emails).
 +
 +
=====MESSAGE_BODY=====
 +
String
 +
 +
The body text of the message, present (usually this will only apply to emails).
 +
 +
=====ATTACHMENTS=====
 +
Integer
 +
 +
The number of attachments available for download associated with this message.
 +
 +
=====RECEIVED_DATETIME=====
 +
DateTime
 +
 +
The date and time on which this message was received by the IMPS Cloud System.
 +
 +
=====ORIGINATOR=====
 +
String
 +
 +
The originating email address or telephone number, if known.
 +
 +
=====DESTINATION=====
 +
String
 +
 +
The destination email address or telephone number, if known.
 +
 +
=====MESSAGE_TAG1=====
 +
String
 +
 +
If a custom tagging operation has been enabled (e.g. OCR) this will return the first tag created for this message.
 +
 +
=====MESSAGE_TAG2=====
 +
String
 +
 +
If a custom tagging operation has been enabled (e.g. OCR) this will return the second tag created for this message.
 +
 +
=====MESSAGE_TAG3=====
 +
String
 +
 +
If a custom tagging operation has been enabled (e.g. OCR) this will return the third tag created for this message.
 +
 +
=====ACTION_SUMMARY=====
 +
String
 +
 +
A summary of any actions that have automatically been performed for this operation, for example email forwarding or relaying.
 +
 +
=====TOTALPAGES=====
 +
Integer
 +
 +
The number of pages in the attachment document (if appropriate)
 +
 +
=====CONNECTSPEED=====
 +
 +
The Baud Rate of the fax transmission if appropriate.
  
 
=== CFRetrieveInboundAttachmentsWS ===
 
=== CFRetrieveInboundAttachmentsWS ===
 +
 +
This operation downloads any attachments associated with an inbound message.
 +
 +
==== Request Elements ====
 +
 +
=====presenceUniqueIdentifier=====
 +
String
 +
 +
This identifies the unique identifier of the inbound message and is specified in CFListInboundMessagesWS.
 +
 +
=====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.
 +
 +
=====specialHandling=====
 +
String
 +
 +
This identifies a special handling Task to pre-process the document prior to delivery. This will typically be configured on a per-account basis depending on your special requirements.
 +
 +
=====specialHandlingInstructions=====
 +
String
 +
 +
Typically an XML instruction or series of instructions to control how the specialHandling Task executes. This is configured on a per-account basis.
 +
 +
====Response Elements====
 +
 +
=====serverResponse=====
 +
String
 +
 +
A three digit response code followed by a colon ( : ) followed by a descriptive message. Please see http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).
 +
 +
=====numberAttachments=====
 +
Integer
 +
 +
This value represents the number of attachments that are included with this response message.
 +
 +
=====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:
 +
 +
=====ATTACHMENT_DATA=====
 +
Base64Binary
 +
 +
This is the actual data of the attachment and contains a base-64 encoded binary array.
 +
 +
=====ATTACHMENT_NAME=====
 +
String
 +
 +
The filename of this attachment.
 +
 +
=====ATTACHMENT_MIME=====
 +
String
 +
 +
The MIME type of this attachment.
  
 
=== CFDeleteMessageWS ===
 
=== CFDeleteMessageWS ===
 +
This operation permanently deletes the specified inbound or outbound message and also deletes any attachment data associated with it.
 +
 +
====Request Elements====
 +
 +
=====presenceUniqueIdentifier=====
 +
String
 +
 +
This specifies the unique identifier of the inbound or outbound message that is to be deleted.
 +
 +
====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
 +
 +
=====InboundOrOutbound=====
 +
String
 +
 +
Specifies whether the message to be deleted is inbound or outbound – must be one of: INBOUND, OUTBOUND. Cannot be omitted.
 +
 +
====Response Elements====
 +
 +
====serverResponse====
 +
String
 +
 +
A three digit response code followed by a colon ( : ) followed by a descriptive message. Please see http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).
  
 
=== CFUploadCoverpageWS ===
 
=== CFUploadCoverpageWS ===
 +
 +
This allows the user to upload an PDF/XML-formatted fax cover page. Cover pages can be referenced by name in the CFCreateMessageWS Operation call and contain keywords that are dynamically replaced when the message is sent to the FAXCOM server.
 +
 +
====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.
 +
 +
=====coverPageName=====
 +
String
 +
 +
This is the name of the cover page to be uploaded to the FAXCOM server.
 +
 +
=====coverPageData=====
 +
String
 +
 +
This is the HTML contents of the cover page.
 +
 +
====Response Elements====
 +
 +
=====serverResponse=====
 +
String
 +
 +
A three digit response code followed by a colon ( : ) followed by a descriptive message. Please see http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).
 +
 +
 +
=== CFRetrieveOutboundAttachmentsWS ===
 +
 +
This allows the user to upload an PDF/XML-formatted fax cover page. Cover pages can be referenced by name in the CFCreateMessageWS Operation call and contain keywords that are dynamically replaced when the message is sent to the FAXCOM server.
 +
 +
====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.
 +
 +
=====presenceUniqueIdentifier=====
 +
String
 +
 +
This is the unique identifier for the queue item which is generated when the message is created.
 +
 +
=====clientMessageId=====
 +
String
 +
 +
The unique identifier supplied by the client in the CFCreateMessageWS operation.
 +
 +
====Response Elements====
 +
 +
=====serverResponse=====
 +
String
 +
 +
A three digit response code followed by a colon ( : ) followed by a descriptive message.
 +
 +
=====fileCount=====
 +
Integer
 +
 +
The number of attachments returned with the operation response.
 +
 +
=====dataTableRow=====
 +
ComplexType
 +
 +
This element may appear one or more times for each attachment. It contains one of each of the following child elements:
 +
 +
=====FILENAME=====
 +
String
 +
 +
The filename of this attachment.
 +
 +
=====FILEBLOB=====
 +
Base64Binary
 +
 +
The base64 binary data of the file attachment.
 +
 +
=====FILETYPE=====
 +
String
 +
 +
The file extension of the attachment
 +
 +
=====SEQUENCE=====
 +
Integer
 +
 +
The sequence in which the attachment appears.
 +
 +
=== CFListOutboundAuditMessagesWS ===
 +
 +
This operation retrieves any audit messages associated with the specified outbound documents.
 +
 +
 +
====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.
 +
 +
=====presenceUniqueIdentifier=====
 +
String
 +
 +
This is the unique identifier for the queue item which is generated when the message is created.
 +
 +
=====clientMessageId=====
 +
String
 +
 +
The unique identifier supplied by the client in the CFCreateMessageWS operation.
 +
 +
====Response Elements====
 +
 +
=====serverResponse=====
 +
String
 +
 +
A three digit response code followed by a colon ( : ) followed by a descriptive message.
 +
 +
 +
=====dataTableRow=====
 +
ComplexType
 +
 +
This element may appear one or more times for each attachment. It contains one of each of the following child elements:
 +
 +
=====ATTEMPT_NUMBER=====
 +
Integer
 +
 +
If appropriate this shows the attempt number corresponding to the audit message.
 +
 +
=====AUDIT_DATE=====
 +
DateTime
 +
 +
The date and time at which this message was recorded.
 +
 +
=====AUDIT_TEXT=====
 +
String
 +
 +
The text of the audit message.
 +
 +
=====DESTINATION=====
 +
String
 +
 +
The destination of the documents.
 +
 +
=====PAGE_COUNT=====
 +
Integer
 +
 +
If appropriate, the number of pages sent.
 +
 +
=====QUEUE_ID=====
 +
String
 +
 +
This should match the presenceUniqueIdentifier.
 +
 +
=====MESSAGE_STATUS=====
 +
String
 +
 +
The status code for this attempt, which will be either (W)aiting, (P)ending, (S)ent, (F)ailed, (R)elayed, (B)usy, (C)anceled, (N)on-busy retry.
 +
 +
=====TRANSMISSION_TIME=====
 +
Integer
 +
 +
The time taken to transmit, or attempt to transmit, the document(s) in seconds.

Latest revision as of 16:57, 19 July 2012

http://www.international-presence.com/wikidocs/images/impscloudlogo.png

IMPSCloud (Integrated Messaging Platform Service) is a hosted, high-volume messaging service which can send, receive and relay faxes, SMS and emails and is specifically designed for the enterprise.

Contents

IMPSCloud

IMPSCloud (Integrated Messaging Platform Service) is a hosted, high-volume messaging service which can send, receive and relay faxes, SMS and emails and is specifically designed for the enterprise.

http://www.international-presence.com/wikidocs/images/soap_architecture_2.png

Standard call procedure

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:

  1. CFCreateMessageWS – (required) creates the new message and places it in a Waiting state on the outgoing queue.
  2. CFAddRecipientWS – (required) 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.
  3. CFAddAttachmentWS – (optional) 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. Attachments do not need to be included if the body of the message is included in the CFCreateMessageWS request.
  4. 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.

SOAP Operations

Please note that the WSDL is located at:

http://www.international-presence.com/impscloud/impscloud.wsdl

CFCreateMessageWS

This Operation creates a new message and places it in a Waiting 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

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 for creating a PDF file – this can be omitted.

messageBodyType

String

This specifies the format of the messageBody text, and the value can be either PDF, 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.

preferredPresenceServer

String

This indicates that a specified Presence server should handle the message. 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. Please see http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).

CFAddRecipientWS

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. Multiple email addresses can be provided as a comma (,) separated list.

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". Multiple telephone numbers can be provided as a comma (,) separated list.


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. Response Elements

clientMessageId

String

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

Response Elements

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 http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).

recipientId

Integer

This is the auto-generated ID for this recipient.


CFAddAttachmentWS

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.

SpecialHandling

String

This denotes that a custom Task should be used to perform any special handling on the document being processed. For example, this can be useful for bespoke functionality such as OCR scanning. This element can be omitted.


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 http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).


CFSendMessageWS

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 http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).

CFCancelMessageWS

This operation requests that a previously created message is cancelled. It may be called at any time after CFCreateMessageWS. Note that this operation may not be effective if a message has already been relayed.

Request Elements

clientMessageId

String

This identifies the message to be cancelled 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 http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).

CFHoldMessageWS

This Operation requests that the specified message is held. This Operation does not guarantee that a message is held as a message may already be in the process of delivery. To release the message at a later date call the CFReleaseMessageWS Operation.

Request Elements

clientMessageId

String

This identifies the message to be held 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 held and is specified in the response to the initial CFCreateMessageWS.

recipientId

String

If a message has multiple recipients, this can be used to specify a single recipient. If all messages to all recipients are to be held, use presenceUniqueIdentifier or clientMessageId.

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 http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).

CFResendMessageWS

This Operation requests that the specified message is resent. If the message is not in a “Sent” or “Cancelled” state, the request will be rejected.

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.

recipientId

String

If a message has multiple recipients, this can be used to specify a single recipient. If all messages to all recipients are to be held, use presenceUniqueIdentifier or clientMessageId.

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.

resendAfterDateTime

String

Optional. If present, the system will not attempt to resend the message until after the specified date and time.

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 http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).

CFReleaseMessageWS

This Operation requests that the specified message is released. This can only be called on messages that are currently in a “Held” state.

Request Elements

clientMessageId

String

This identifies the message to be released 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 released and is specified in the response to the initial CFCreateMessageWS.

recipientId

String

If a message has multiple recipients, this can be used to specify a single recipient. If all recipients are to be released, use presenceUniqueIdentifier or clientMessageId.

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 http://www.international-presence.com/wikidocs/index.php?title=CloudFax_Server_Responses for further information (document in progress).

CFGetMessageStatusWS

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 http://www.international-presence.com/wikidocs/index.php?title=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 ( W ) :- The message has not yet been released with CFSendMessageWS
  • PENDING ( P ) :- The message has been released for delivery
  • RELAYED ( R ):- The message is in the process of delivery.
  • CANCELLED ( C ):- The message has been cancelled prior to sending
  • PARTIAL ( L ) :- The message was partially sent to one or more recipients – check individual recipient statuses for more information (see dataTableRow below).
  • SENT ( S ):- The message delivery has completed.
  • FAILED ( F ):- The message failed in its entirety.
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

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. Please use the single character abbreviation specified above.

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.international-presence.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 RELAYED :- 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). SENT :- 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.

CFListInboundMessagesWS

This Operation returns a filtered list of inbound messages.

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.

minimumReceivedDate

DateTime

This element may appear once or zero times. If present, messages returned will be limited to those that were received on or after the date specified.

maximumReceivedDate

dateTime

This element may appear once or zero times. If present, messages returned will be limited to those that were received on or after the date specified.

messageTypeFilter

String

If present, messages will be limited to the type specified, which may be one of:

  • FAX
  • EMAIL
  • SMS
destinationFilter

String

If present, messages will be limited to those with the intended destination. Destination can include the asterisk (*) character as a wildcard.

originatorFilter

String

If present, messages will be limited to those with the specified originator number or address. Originator string can include the asterisk (*) character as a wildcard.

messageTag1Filter

String

If a tagging mechanism has been set up for incoming messages (such as OCR), this can be used to filter the messages returned by the appropriate tag.

messageTag2Filter

String

If a tagging mechanism has been set up for incoming messages (such as OCR), this can be used to filter the messages returned by the appropriate tag.

messageTag3Filter

String

If a tagging mechanism has been set up for incoming messages (such as OCR), this can be used to filter the messages returned by the appropriate tag.

restrictToNewMessages

Boolean

If true, only messages that have not previously been reported will be listed. Once a message has been listed using this operation it will be marked as reported and will not appear in future lists where this value is set to True.

Response Elements

serverResponse

String

A three digit response code followed by a colon ( : ) followed by a descriptive message. Please see http://www.international-presence.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

The unique identifier assigned to this message on receipt

MESSAGE_TYPE

String

The type of message. May be one of: FAX, EMAIL, SMS.

SUBJECT

String

The subject line of the message, if present (usually this will only apply to emails).

MESSAGE_BODY

String

The body text of the message, present (usually this will only apply to emails).

ATTACHMENTS

Integer

The number of attachments available for download associated with this message.

RECEIVED_DATETIME

DateTime

The date and time on which this message was received by the IMPS Cloud System.

ORIGINATOR

String

The originating email address or telephone number, if known.

DESTINATION

String

The destination email address or telephone number, if known.

MESSAGE_TAG1

String

If a custom tagging operation has been enabled (e.g. OCR) this will return the first tag created for this message.

MESSAGE_TAG2

String

If a custom tagging operation has been enabled (e.g. OCR) this will return the second tag created for this message.

MESSAGE_TAG3

String

If a custom tagging operation has been enabled (e.g. OCR) this will return the third tag created for this message.

ACTION_SUMMARY

String

A summary of any actions that have automatically been performed for this operation, for example email forwarding or relaying.

TOTALPAGES

Integer

The number of pages in the attachment document (if appropriate)

CONNECTSPEED

The Baud Rate of the fax transmission if appropriate.

CFRetrieveInboundAttachmentsWS

This operation downloads any attachments associated with an inbound message.

Request Elements

presenceUniqueIdentifier

String

This identifies the unique identifier of the inbound message and is specified in CFListInboundMessagesWS.

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.

specialHandling

String

This identifies a special handling Task to pre-process the document prior to delivery. This will typically be configured on a per-account basis depending on your special requirements.

specialHandlingInstructions

String

Typically an XML instruction or series of instructions to control how the specialHandling Task executes. This is configured on a per-account basis.

Response Elements

serverResponse

String

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

numberAttachments

Integer

This value represents the number of attachments that are included with this response message.

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:

ATTACHMENT_DATA

Base64Binary

This is the actual data of the attachment and contains a base-64 encoded binary array.

ATTACHMENT_NAME

String

The filename of this attachment.

ATTACHMENT_MIME

String

The MIME type of this attachment.

CFDeleteMessageWS

This operation permanently deletes the specified inbound or outbound message and also deletes any attachment data associated with it.

Request Elements

presenceUniqueIdentifier

String

This specifies the unique identifier of the inbound or outbound message that is to be deleted.

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

InboundOrOutbound

String

Specifies whether the message to be deleted is inbound or outbound – must be one of: INBOUND, OUTBOUND. Cannot be omitted.

Response Elements

serverResponse

String

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

CFUploadCoverpageWS

This allows the user to upload an PDF/XML-formatted fax cover page. Cover pages can be referenced by name in the CFCreateMessageWS Operation call and contain keywords that are dynamically replaced when the message is sent to the FAXCOM server.

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.

coverPageName

String

This is the name of the cover page to be uploaded to the FAXCOM server.

coverPageData

String

This is the HTML contents of the cover page.

Response Elements

serverResponse

String

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


CFRetrieveOutboundAttachmentsWS

This allows the user to upload an PDF/XML-formatted fax cover page. Cover pages can be referenced by name in the CFCreateMessageWS Operation call and contain keywords that are dynamically replaced when the message is sent to the FAXCOM server.

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.

presenceUniqueIdentifier

String

This is the unique identifier for the queue item which is generated when the message is created.

clientMessageId

String

The unique identifier supplied by the client in the CFCreateMessageWS operation.

Response Elements

serverResponse

String

A three digit response code followed by a colon ( : ) followed by a descriptive message.

fileCount

Integer

The number of attachments returned with the operation response.

dataTableRow

ComplexType

This element may appear one or more times for each attachment. It contains one of each of the following child elements:

FILENAME

String

The filename of this attachment.

FILEBLOB

Base64Binary

The base64 binary data of the file attachment.

FILETYPE

String

The file extension of the attachment

SEQUENCE

Integer

The sequence in which the attachment appears.

CFListOutboundAuditMessagesWS

This operation retrieves any audit messages associated with the specified outbound documents.


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.

presenceUniqueIdentifier

String

This is the unique identifier for the queue item which is generated when the message is created.

clientMessageId

String

The unique identifier supplied by the client in the CFCreateMessageWS operation.

Response Elements

serverResponse

String

A three digit response code followed by a colon ( : ) followed by a descriptive message.


dataTableRow

ComplexType

This element may appear one or more times for each attachment. It contains one of each of the following child elements:

ATTEMPT_NUMBER

Integer

If appropriate this shows the attempt number corresponding to the audit message.

AUDIT_DATE

DateTime

The date and time at which this message was recorded.

AUDIT_TEXT

String

The text of the audit message.

DESTINATION

String

The destination of the documents.

PAGE_COUNT

Integer

If appropriate, the number of pages sent.

QUEUE_ID

String

This should match the presenceUniqueIdentifier.

MESSAGE_STATUS

String

The status code for this attempt, which will be either (W)aiting, (P)ending, (S)ent, (F)ailed, (R)elayed, (B)usy, (C)anceled, (N)on-busy retry.

TRANSMISSION_TIME

Integer

The time taken to transmit, or attempt to transmit, the document(s) in seconds.