Difference between revisions of "IMPSCloud"
(→messageTypeFilter) |
(→MESSAGE_STATUS) |
||
(12 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 | ||
− | + | == 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: | |
− | + | ||
− | + | # [[#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 == | == SOAP Operations == | ||
Line 565: | Line 560: | ||
This describes the status of the overall message. It will be one of the following: | 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 | + | *WAITING ( W ) :- The message has not yet been released with CFSendMessageWS |
− | PENDING ( P ) :- The message has been released for delivery | + | *PENDING ( P ) :- The message has been released for delivery |
− | RELAYED ( R ):- The message is in the process of delivery. | + | *RELAYED ( R ):- The message is in the process of delivery. |
− | CANCELLED ( C ):- The message has been cancelled prior to sending | + | *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). | + | *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. | + | *SENT ( S ):- The message delivery has completed. |
− | FAILED ( F ):- The message failed in its entirety. | + | *FAILED ( F ):- The message failed in its entirety. |
=====pages===== | =====pages===== | ||
Line 589: | Line 584: | ||
This indicates the delivery status for this recipient and will be one of the following: | This indicates the delivery status for this recipient and will be one of the following: | ||
− | H=Held | + | * H=Held |
− | W=Waiting (not yet released) | + | * W=Waiting (not yet released) |
− | F=Failed | + | * F=Failed |
− | S=Sent | + | * S=Sent |
− | T=Timed/Scheduled resend | + | * T=Timed/Scheduled resend |
− | R=Relayed | + | * R=Relayed |
− | B=Busy | + | * B=Busy |
− | P=Pending | + | * P=Pending |
− | N=Non-Busy retry | + | * N=Non-Busy retry |
=====STATUS_DESCRIPTION===== | =====STATUS_DESCRIPTION===== | ||
Line 718: | Line 713: | ||
This indicates the delivery status for this recipient and will be one of the following: | This indicates the delivery status for this recipient and will be one of the following: | ||
− | H=Held | + | * H=Held |
− | W=Waiting (not yet released) | + | * W=Waiting (not yet released) |
− | F=Failed | + | * F=Failed |
− | S=Sent | + | * S=Sent |
− | T=Timed/Scheduled resend | + | * T=Timed/Scheduled resend |
− | R=Relayed | + | * R=Relayed |
− | B=Busy | + | * B=Busy |
− | P=Pending | + | * P=Pending |
− | N=Non-Busy retry | + | * N=Non-Busy retry |
=====RECIPIENT_EMAIL===== | =====RECIPIENT_EMAIL===== | ||
Line 894: | Line 889: | ||
A summary of any actions that have automatically been performed for this operation, for example email forwarding or relaying. | 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 === | ||
Line 915: | Line 919: | ||
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. | ||
+ | |||
+ | =====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==== | ====Response Elements==== | ||
Line 1,013: | Line 1,027: | ||
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). | 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
- 1 IMPSCloud
- 1.1 Standard call procedure
- 1.2 SOAP Operations
- 1.2.1 CFCreateMessageWS
- 1.2.1.1 Request Elements
- 1.2.1.1.1 username
- 1.2.1.1.2 password
- 1.2.1.1.3 clientMessageId
- 1.2.1.1.4 messageGroupId
- 1.2.1.1.5 coverPage
- 1.2.1.1.6 memo
- 1.2.1.1.7 messageBody
- 1.2.1.1.8 messageBodyType
- 1.2.1.1.9 messagePriority
- 1.2.1.1.10 resolution
- 1.2.1.1.11 sendTime
- 1.2.1.1.12 senderEmail
- 1.2.1.1.13 senderName
- 1.2.1.1.14 senderNumber
- 1.2.1.1.15 subject
- 1.2.1.1.16 preferredPresenceServer
- 1.2.1.2 Response Elements
- 1.2.1.1 Request Elements
- 1.2.2 CFAddRecipientWS
- 1.2.3 CFAddAttachmentWS
- 1.2.4 CFSendMessageWS
- 1.2.5 CFCancelMessageWS
- 1.2.6 CFHoldMessageWS
- 1.2.7 CFResendMessageWS
- 1.2.8 CFReleaseMessageWS
- 1.2.9 CFGetMessageStatusWS
- 1.2.9.1 Request Elements
- 1.2.9.2 Response Elements
- 1.2.9.2.1 clientMessageId
- 1.2.9.2.2 presenceUniqueIdentifier
- 1.2.9.2.3 serverResponse
- 1.2.9.2.4 messageStatus
- 1.2.9.2.5 pages
- 1.2.9.2.6 dataTableRow
- 1.2.9.2.7 RECIPIENT_ID
- 1.2.9.2.8 DELIVERY_STATUS
- 1.2.9.2.9 STATUS_DESCRIPTION
- 1.2.9.2.10 RECIPIENT_EMAIL
- 1.2.9.2.11 RECIPIENT_PHONE
- 1.2.9.2.12 RECIPIENT_TYPE
- 1.2.9.2.13 NUMBER_ATTEMPTS
- 1.2.9.2.14 LAST_ATTEMPT
- 1.2.9.2.15 NEXT_ATTEMPT
- 1.2.10 CFListOutboundMessagesWS
- 1.2.10.1 Request Elements
- 1.2.10.2 Response Elements
- 1.2.10.2.1 serverResponse
- 1.2.10.2.2 dataTableRow
- 1.2.10.2.3 PRESENCE_UNIQUE_IDENTIFIER
- 1.2.10.2.4 CLIENT_UNIQUE_IDENTIFIER
- 1.2.10.2.5 GROUP_ID
- 1.2.10.2.6 MESSAGE_STATUS
- 1.2.10.2.7 RECIPIENT_ID
- 1.2.10.2.8 DELIVERY_STATUS
- 1.2.10.2.9 RECIPIENT_EMAIL
- 1.2.10.2.10 RECIPIENT_PHONE
- 1.2.10.2.11 RECIPIENT_TYPE
- 1.2.10.2.12 NUMBER_ATTEMPTS
- 1.2.10.2.13 LAST_ATTEMPT
- 1.2.10.2.14 NEXT_ATTEMPT
- 1.2.11 CFListInboundMessagesWS
- 1.2.11.1 Request Elements
- 1.2.11.2 Response Elements
- 1.2.11.2.1 serverResponse
- 1.2.11.2.2 dataTableRow
- 1.2.11.2.3 PRESENCE_UNIQUE_IDENTIFIER
- 1.2.11.2.4 MESSAGE_TYPE
- 1.2.11.2.5 SUBJECT
- 1.2.11.2.6 MESSAGE_BODY
- 1.2.11.2.7 ATTACHMENTS
- 1.2.11.2.8 RECEIVED_DATETIME
- 1.2.11.2.9 ORIGINATOR
- 1.2.11.2.10 DESTINATION
- 1.2.11.2.11 MESSAGE_TAG1
- 1.2.11.2.12 MESSAGE_TAG2
- 1.2.11.2.13 MESSAGE_TAG3
- 1.2.11.2.14 ACTION_SUMMARY
- 1.2.11.2.15 TOTALPAGES
- 1.2.11.2.16 CONNECTSPEED
- 1.2.12 CFRetrieveInboundAttachmentsWS
- 1.2.13 CFDeleteMessageWS
- 1.2.14 CFUploadCoverpageWS
- 1.2.15 CFRetrieveOutboundAttachmentsWS
- 1.2.16 CFListOutboundAuditMessagesWS
- 1.2.1 CFCreateMessageWS
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:
- CFCreateMessageWS – (required) creates the new message and places it in a Waiting state on the outgoing queue.
- 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 – (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 - 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
- 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.