Skype for Business - messagingInvitation Resource

messagingInvitation

  • JSON
  • XML

Represents an invitation to a conversation for the messaging modality.

Web link

For more on web links, see Web Links.

Name Description
relThe resource that this link points to. In JSON, this is the outer container.
hrefThe location of this resource on the server, and the target of an HTTP operation.

Resource description

This resource can be incoming or outgoing. If outgoing, the messagingInvitation can be created in one of two ways. First, startMessaging will create a messagingInvitation that also creates a conversation. Second, addMessaging will attempt to add the messaging modality to an existing conversation. This resource assists in keeping track of the invitation status; for example, the invitation could be accepted, declined, or ignored. An outgoing messagingInvitation will be in the 'Connecting' state while waiting for the recipient to accept or decline it; during this time, the messagingInvitation can be terminated using cancel. Note that if the recipient does not respond in approximately thirty seconds, the messagingInvitation will complete with failure. Ultimately, the messagingInvitation will complete with success or failure (in which case a reason is supplied). If the messagingInvitation succeeds, the participant that accepts it will be provided (acceptedByParticipant). If incoming, the messagingInvitation can create a new conversation or attempt to add the messaging modality to an existing conversation.

Properties

Name Description
customContent Custom Content.
direction The direction of the invitation.
importance The importance.
message The first message represented in this invitation.
operationId The operation ID as supplied by the client.

The maximum length is 50 characters.

state The invitation state.
subject The subject.

The maximum length is 250 characters.

threadId The thread ID of the conversation.
to The target of this invitation.

Links

This resource can have the following relationships.

Link Description
selfThe link to the current resource.
accept Accepts an incoming invitation.
acceptedByContact Represents the contact who ultimately accepted an incoming invitation.
cancel Cancels the corresponding invitation.
conversation Represents the local participants perspective on a multi-modal, multi-party communication.
decline Declines an incoming invitation.
derivedMessaging Represents the messaging modality in a derivedConversation.
from Represents the participant that sent an invitation.
messaging Represents the instant messaging modality in a conversation.
onBehalfOf Represents the contact on whose behalf the invitation was received.
to Represents the originally intended target of the invitation as a contact.
acceptedByParticipant Represents the remote participant who accepted the invitation of the user.
from Represents the participant that sent an invitation.

Events

  • started
  • updated
  • completed
Resource Priority Sender Reason
messagingInvitationHighcommunication Delivered when a messaging invitation is started. This occurs when the application starts the messaging modality.

Sample of returned event data.

This sample is given only as an illustration of event syntax. The semantic content is not guaranteed to correspond to a valid scenario.

{
  "_links" : {
    "self" : {
      "href" : "http://sample:80/ucwa/v1/applications/appId/events?ack=42"
    },
    "next" : {
      "href" : "http://sample:80/ucwa/v1/applications/appId/events?ack=42"
    }
  },
  "sender" : [
    {
      "rel" : "communication",
      "href" : "https://fe1.contoso.com:443//v1/applications/970/communication",
      "events" : [
        {
          "link" : {
            "rel" : "messagingInvitation",
            "href" : "https://fe1.contoso.com:443//v1/applications/970/communication/invitations/212"
          },
          "type" : "started"
        }
      ]
    }
  ]
}
Resource Priority Sender Reason
messagingInvitationHighcommunication Delivered when the messaging invitation is updated.

Sample of returned event data.

This sample is given only as an illustration of event syntax. The semantic content is not guaranteed to correspond to a valid scenario.

{
  "_links" : {
    "self" : {
      "href" : "http://sample:80/ucwa/v1/applications/appId/events?ack=3"
    },
    "next" : {
      "href" : "http://sample:80/ucwa/v1/applications/appId/events?ack=3"
    }
  },
  "sender" : [
    {
      "rel" : "communication",
      "href" : "https://fe1.contoso.com:443//v1/applications/970/communication",
      "events" : [
        {
          "link" : {
            "rel" : "messagingInvitation",
            "href" : "https://fe1.contoso.com:443//v1/applications/970/communication/invitations/212"
          },
          "type" : "updated"
        }
      ]
    }
  ]
}
Resource Priority Sender Reason
messagingInvitationHighcommunication Delivered when the messaging invitation completes.

Sample of returned event data.

This sample is given only as an illustration of event syntax. The semantic content is not guaranteed to correspond to a valid scenario.

{
  "_links" : {
    "self" : {
      "href" : "http://sample:80/ucwa/v1/applications/appId/events?ack=54"
    },
    "next" : {
      "href" : "http://sample:80/ucwa/v1/applications/appId/events?ack=54"
    }
  },
  "sender" : [
    {
      "rel" : "communication",
      "href" : "https://fe1.contoso.com:443//v1/applications/970/communication",
      "events" : [
        {
          "link" : {
            "rel" : "messagingInvitation",
            "href" : "https://fe1.contoso.com:443//v1/applications/970/communication/invitations/212"
          },
          "type" : "completed"
        }
      ]
    }
  ]
}

Asynchronous reason codes

The completed event is sent on the event channel when the operation is finished. A status value of "success" indicates that the operation completed successfully.A status value of "failure" indicates that the operation failed. In case of failure, the error code and subcode are sent on the event channel.The following table shows the errors that are possible for this resource.

It is recommended that applications handle the error codes shown here. Applications can optionally display subcodes and messages in their user interface.

  • Conflict
  • Subcode Reason
    AlreadyExists There was a problem joining the conference focus.
    AlreadyExists
    None
    None The resource is being deleted.
    None There was a problem joining the conference focus.
    TooManyGroups

  • EntityTooLarge
  • Subcode Reason
    None The request was too large.

  • Forbidden
  • Subcode Reason
    AnonymousNotAllowed This meeting does not allow dial-out by attendees.
    DialoutNotAllowed This meeting does not allow dial-out by attendees.
    FederationRequired Federation required.
    InviteesOnly User not allowed in closed meeting.
    ModalityNotSupported The requested modality is not allowed in the conference.
    ModalityNotSupported The remote client does not support the requested modality.
    None Participant is not connected to meeting.
    Unreachable The destination is not reachable.

  • Informational
  • Subcode Reason
    AutoAccepted Invitation was auto-accepted
    Canceled Request was canceled.
    ConnectedElsewhere The invitation was accepted at another location.
    DerivedConversation A derived conversation was created.
    MediaFallback The invitation was cancelled by the media fallback logic.
    Missed The invitation was missed.

  • LocalFailure
  • Subcode Reason
    Canceled The invitation was cancelled by the local user.
    Declined The invitation was declined by the local user.
    None Local failure.
    Timeout The invitation timed out locally.

  • NotFound
  • Subcode Reason
    DestinationNotFound The destination identity could not be found.

  • RemoteFailure
  • Subcode Reason
    AnotherOperationPending Remote Failure with another operation pending.
    Busy The remote side indicated that it is too busy at this time to accept the invitation.
    Canceled The invitation was cancelled by a remote user.
    Declined The outgoing invitation was declined.
    DoNotDisturb The remote party does not want to be disturbed at this time.
    None Remote failure.
    NotAcceptable The remote client is unable to accept the call at this time or context.
    NotAllowed The remote party is not allowed to process this request due to policy.
    RepliedWithOtherModality Replied with another modality.
    TemporarilyUnavailable The remote is temporarily unavailable.
    TemporarilyUnavailable Some service is temporarily unavailable.
    ThreadIdAlreadyExists The invitation was not accepted as the remote is already in a conversation with the same thread ID.
    Timeout The operation has timed out on the callee's end.
    UnsupportedMediaType Unsupported media.

  • ServiceFailure
  • Subcode Reason
    CallbackChannelError
    EscalationFailed Escalation failed.
    InvalidExchangeServerVersion
    None Internal server error.
    Timeout The operation timed out.
    Unavailable There is no suitable service available for this modality in this conference.

  • Timeout
  • Subcode Reason
    None The operation has timed out.
    None Remote failure.

Operations

  • GET

Returns a representation of an invitation to a conversation for the messaging modality.

Request body

None

Response body

The response from a GET request contains the properties and links shown in the Properties and Links sections at the top of this page.

Synchronous errors

The errors below (if any) are specific to this resource. Generic errors that can apply to any resource are covered in Generic synchronous errors.

Error Code Subcode Description
BadRequest400None Something is wrong with the entire request (malformed XML/JSON, for example).
BadRequest400ParameterValidationFailure Incorrect parameters were provided for the request (for example, the requested conference subject exceeds the maximum length).
Gone410None The content-type is not supported.
NotFound404None The resource does not exist.
ServiceFailure500InvalidExchangeServerVersion
Conflict409AlreadyExists
Conflict409TooManyGroups
Conflict409None

Examples

Request

Get https://fe1.contoso.com:443//v1/applications/970/communication/invitations/212 HTTP/1.1
Authorization: Bearer cwt=PHNhbWw6QXNzZXJ0aW9uIHhtbG5...uZm8
Host: fe1.contoso.com
Accept: application/json

  

JSON Response

This sample is given only as an illustration of response syntax. The semantic content is not guaranteed to correspond to a valid scenario.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 5145
{
  "rel" : "messagingInvitation",
  "direction" : "Incoming",
  "importance" : "Normal",
  "operationId" : "74cb7404e0a247d5a2d4eb0376a47dbf",
  "state" : "Connecting",
  "subject" : "Strategyfornextquarter",
  "threadId" : "292e0aaef36c426a97757f43dda19d06",
  "to" : "sip : john@contoso.com",
  "_links" : {
    "self" : {
      "href" : "//v1/applications/970/communication/invitations/212"
    },
    "customContent" : {
      "href" : "data : application/sdp;base64,
      base64-encoded-sdp"
    },
    "message" : {
      "href" : "data : text/plain;base64,
      somebase64encodedmessage"
    },
    "from" : {
      "href" : "//v1/applications/970/communication/conversations/314/participants/832"
    },
    "accept" : {
      "href" : "//v1/applications/970/communication/invitations/127/accept"
    },
    "acceptedByContact" : {
      "href" : "//v1/applications/970/people/850"
    },
    "cancel" : {
      "href" : "//v1/applications/970/communication/invitations/127/cancel"
    },
    "conversation" : {
      "href" : "//v1/applications/970/communication/conversations/314"
    },
    "decline" : {
      "href" : "//v1/applications/970/communication/invitations/127/decline"
    },
    "derivedMessaging" : {
      "href" : "//v1/applications/970/communication/invitations/127/derivedMessaging"
    },
    "messaging" : {
      "href" : "//v1/applications/970/communication/conversations/314/messaging"
    },
    "onBehalfOf" : {
      "href" : "//v1/applications/970/people/825"
    },
    "to" : {
      "href" : "//v1/applications/970/people/322"
    }
  },
  "_embedded" : {
    "acceptedByParticipant" : [
      {
        "rel" : "participant",
        "anonymous" : true,
        "name" : "JoeSmith",
        "organizer" : true,
        "otherPhoneNumber" : "tel : +14251111111",
        "role" : "Attendee",
        "sourceNetwork" : "SameEnterprise",
        "uri" : "sip : john@contoso.com",
        "workPhoneNumber" : "tel : +14251111111",
        "_links" : {
          "self" : {
            "href" : "//v1/applications/970/communication/conversations/314/participants/843"
          },
          "admit" : {
            "href" : "//v1/applications/970/communication/conversations/314/participants/843/admit"
          },
          "contact" : {
            "href" : "//v1/applications/970/people/235"
          },
          "contactPhoto" : {
            "href" : "//v1/applications/970/people/235/contactPhoto"
          },
          "contactPresence" : {
            "href" : "//v1/applications/970/people/235/contactPresence"
          },
          "conversation" : {
            "href" : "//v1/applications/970/communication/conversations/314"
          },
          "demote" : {
            "href" : "//v1/applications/970/communication/conversations/314/participants/843/demote"
          },
          "eject" : {
            "href" : "//v1/applications/970/communication/conversations/314/participants/843/eject"
          },
          "me" : {
            "href" : "//v1/applications/970/me"
          },
          "participantApplicationSharing" : {
            "href" : "//v1/applications/970/communication/conversations/314/participants/843/participantApplicationSharing"
          },
          "participantAudio" : {
            "href" : "//v1/applications/970/communication/conversations/314/participants/843/participantAudio"
          },
          "participantDataCollaboration" : {
            "href" : "//v1/applications/970/communication/conversations/314/participants/843/participantDataCollaboration"
          },
          "participantMessaging" : {
            "href" : "//v1/applications/970/communication/conversations/314/participants/843/participantMessaging"
          },
          "participantPanoramicVideo" : {
            "href" : "//v1/applications/970/communication/conversations/314/participants/843/participantPanoramicVideo"
          },
          "participantVideo" : {
            "href" : "//v1/applications/970/communication/conversations/314/participants/843/participantVideo"
          },
          "promote" : {
            "href" : "//v1/applications/970/communication/conversations/314/participants/843/promote"
          },
          "reject" : {
            "href" : "//v1/applications/970/communication/conversations/314/participants/843/reject"
          }
        }
      }
    ],
    "from" : {
      "rel" : "participant",
      "anonymous" : true,
      "name" : "JoeSmith",
      "organizer" : true,
      "otherPhoneNumber" : "tel : +14251111111",
      "role" : "Attendee",
      "sourceNetwork" : "SameEnterprise",
      "uri" : "sip : john@contoso.com",
      "workPhoneNumber" : "tel : +14251111111",
      "_links" : {
        "self" : {
          "href" : "//v1/applications/970/communication/conversations/314/participants/843"
        },
        "admit" : {
          "href" : "//v1/applications/970/communication/conversations/314/participants/843/admit"
        },
        "contact" : {
          "href" : "//v1/applications/970/people/235"
        },
        "contactPhoto" : {
          "href" : "//v1/applications/970/people/235/contactPhoto"
        },
        "contactPresence" : {
          "href" : "//v1/applications/970/people/235/contactPresence"
        },
        "conversation" : {
          "href" : "//v1/applications/970/communication/conversations/314"
        },
        "demote" : {
          "href" : "//v1/applications/970/communication/conversations/314/participants/843/demote"
        },
        "eject" : {
          "href" : "//v1/applications/970/communication/conversations/314/participants/843/eject"
        },
        "me" : {
          "href" : "//v1/applications/970/me"
        },
        "participantApplicationSharing" : {
          "href" : "//v1/applications/970/communication/conversations/314/participants/843/participantApplicationSharing"
        },
        "participantAudio" : {
          "href" : "//v1/applications/970/communication/conversations/314/participants/843/participantAudio"
        },
        "participantDataCollaboration" : {
          "href" : "//v1/applications/970/communication/conversations/314/participants/843/participantDataCollaboration"
        },
        "participantMessaging" : {
          "href" : "//v1/applications/970/communication/conversations/314/participants/843/participantMessaging"
        },
        "participantPanoramicVideo" : {
          "href" : "//v1/applications/970/communication/conversations/314/participants/843/participantPanoramicVideo"
        },
        "participantVideo" : {
          "href" : "//v1/applications/970/communication/conversations/314/participants/843/participantVideo"
        },
        "promote" : {
          "href" : "//v1/applications/970/communication/conversations/314/participants/843/promote"
        },
        "reject" : {
          "href" : "//v1/applications/970/communication/conversations/314/participants/843/reject"
        }
      }
    }
  }
}
  

Request

Get https://fe1.contoso.com:443//v1/applications/970/communication/invitations/212 HTTP/1.1
Authorization: Bearer cwt=PHNhbWw6QXNzZXJ0aW9uIHhtbG5...uZm8
Host: fe1.contoso.com
Accept: application/xml

  

XML Response

This sample is given only as an illustration of response syntax. The semantic content is not guaranteed to correspond to a valid scenario.

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 6204
<?xml version="1.0" encoding="utf-8"?>
<resource rel="messagingInvitation" href="//v1/applications/970/communication/invitations/212" xmlns="http://schemas.microsoft.com/rtc/2012/03/ucwa">
  <link rel="customContent" href="data:application/sdp;base64,base64-encoded-sdp" />
  <link rel="message" href="data:text/plain;base64,somebase64encodedmessage" />
  <link rel="from" href="//v1/applications/970/communication/conversations/314/participants/832" />
  <link rel="accept" href="//v1/applications/970/communication/invitations/127/accept" />
  <link rel="acceptedByContact" href="//v1/applications/970/people/850" />
  <link rel="cancel" href="//v1/applications/970/communication/invitations/127/cancel" />
  <link rel="conversation" href="//v1/applications/970/communication/conversations/314" />
  <link rel="decline" href="//v1/applications/970/communication/invitations/127/decline" />
  <link rel="derivedMessaging" href="//v1/applications/970/communication/invitations/127/derivedMessaging" />
  <link rel="messaging" href="//v1/applications/970/communication/conversations/314/messaging" />
  <link rel="onBehalfOf" href="//v1/applications/970/people/825" />
  <link rel="to" href="//v1/applications/970/people/322" />
  <property name="rel">messagingInvitation</property>
  <property name="direction">Incoming</property>
  <property name="importance">Normal</property>
  <property name="operationId">74cb7404e0a247d5a2d4eb0376a47dbf</property>
  <property name="state">Connected</property>
  <property name="subject">Strategy for next quarter</property>
  <property name="threadId">292e0aaef36c426a97757f43dda19d06</property>
  <property name="to">sip:john@contoso.com</property>
  <resource rel="acceptedByParticipant" href="//v1/applications/970/communication/conversations/314/participants/843">
    <link rel="admit" href="//v1/applications/970/communication/conversations/314/participants/843/admit" />
    <link rel="contact" href="//v1/applications/970/people/235" />
    <link rel="contactPhoto" href="//v1/applications/970/people/235/contactPhoto" />
    <link rel="contactPresence" href="//v1/applications/970/people/235/contactPresence" />
    <link rel="conversation" href="//v1/applications/970/communication/conversations/314" />
    <link rel="demote" href="//v1/applications/970/communication/conversations/314/participants/843/demote" />
    <link rel="eject" href="//v1/applications/970/communication/conversations/314/participants/843/eject" />
    <link rel="me" href="//v1/applications/970/me" />
    <link rel="participantApplicationSharing" href="//v1/applications/970/communication/conversations/314/participants/843/participantApplicationSharing" />
    <link rel="participantAudio" href="//v1/applications/970/communication/conversations/314/participants/843/participantAudio" />
    <link rel="participantDataCollaboration" href="//v1/applications/970/communication/conversations/314/participants/843/participantDataCollaboration" />
    <link rel="participantMessaging" href="//v1/applications/970/communication/conversations/314/participants/843/participantMessaging" />
    <link rel="participantPanoramicVideo" href="//v1/applications/970/communication/conversations/314/participants/843/participantPanoramicVideo" />
    <link rel="participantVideo" href="//v1/applications/970/communication/conversations/314/participants/843/participantVideo" />
    <link rel="promote" href="//v1/applications/970/communication/conversations/314/participants/843/promote" />
    <link rel="reject" href="//v1/applications/970/communication/conversations/314/participants/843/reject" />
    <property name="rel">participant</property>
    <property name="anonymous">True</property>
    <property name="name">Joe Smith</property>
    <property name="organizer">True</property>
    <property name="otherPhoneNumber">tel:+14251111111</property>
    <property name="role">Attendee</property>
    <property name="sourceNetwork">SameEnterprise</property>
    <property name="uri">sip:john@contoso.com</property>
    <property name="workPhoneNumber">tel:+14251111111</property>
  </resource>
  <resource rel="from" href="//v1/applications/970/communication/conversations/314/participants/843">
    <link rel="admit" href="//v1/applications/970/communication/conversations/314/participants/843/admit" />
    <link rel="contact" href="//v1/applications/970/people/235" />
    <link rel="contactPhoto" href="//v1/applications/970/people/235/contactPhoto" />
    <link rel="contactPresence" href="//v1/applications/970/people/235/contactPresence" />
    <link rel="conversation" href="//v1/applications/970/communication/conversations/314" />
    <link rel="demote" href="//v1/applications/970/communication/conversations/314/participants/843/demote" />
    <link rel="eject" href="//v1/applications/970/communication/conversations/314/participants/843/eject" />
    <link rel="me" href="//v1/applications/970/me" />
    <link rel="participantApplicationSharing" href="//v1/applications/970/communication/conversations/314/participants/843/participantApplicationSharing" />
    <link rel="participantAudio" href="//v1/applications/970/communication/conversations/314/participants/843/participantAudio" />
    <link rel="participantDataCollaboration" href="//v1/applications/970/communication/conversations/314/participants/843/participantDataCollaboration" />
    <link rel="participantMessaging" href="//v1/applications/970/communication/conversations/314/participants/843/participantMessaging" />
    <link rel="participantPanoramicVideo" href="//v1/applications/970/communication/conversations/314/participants/843/participantPanoramicVideo" />
    <link rel="participantVideo" href="//v1/applications/970/communication/conversations/314/participants/843/participantVideo" />
    <link rel="promote" href="//v1/applications/970/communication/conversations/314/participants/843/promote" />
    <link rel="reject" href="//v1/applications/970/communication/conversations/314/participants/843/reject" />
    <property name="rel">participant</property>
    <property name="anonymous">True</property>
    <property name="name">Joe Smith</property>
    <property name="organizer">True</property>
    <property name="otherPhoneNumber">tel:+14251111111</property>
    <property name="role">Attendee</property>
    <property name="sourceNetwork">SameEnterprise</property>
    <property name="uri">sip:john@contoso.com</property>
    <property name="workPhoneNumber">tel:+14251111111</property>
  </resource>
</resource>