Social Contact API Parameters

Parameters are optional unless otherwise noted.

Parameter

Description

Notes

author

The social contact author name.

String.

Required for POST.

description

The body of the social contact.

String.

extensionField

A wrapper tag for a custom name and value pair.

For email contacts, Customer Collaboration Platform stores the following attributes in the extension fields:

  • emailUniqueIdInFolder: The ID of the email message. The ID identifies the email message in its folder. The ID is not valid if the email is moved from the folder associated with the feed that captured the email.

  • emailFrom: A comma-separated list of email users who authored the email.

  • emailReplyTo: A comma-separated list of the email users to include in a reply to the email message.

  • agentId: The agent who is currently handling the email contact. If an agent replies to a customer email and the customer replies to the agent's reply, this field can be used to route the customer reply to the same agent.

  • customer_attachment_names: A quoted and comma-separated list of email attachment filenames Quotes in filenames are escaped using a backslash quote (/")

    For example: "file1.txt","file2.txt"

extensionFields

A collection of custom name and value pairs.

The person submitting the social contact may specify up to 100 pairs, and the entire collection can contain up to one megabyte of information.

To update user data, provide a new value for the existing extension field name. If you include an extension field element with the name but no value, the corresponding name and value pair will be deleted during the update.

feedRefURL

The feed refURL that the social contact is associated with.

String.

Required for POST.

isSoftLocked

Indicates that the social contact should not be modified, but is not enforced in the API.

Boolean.

The Customer Collaboration Platform UI will not permit any modifications via the UI to a social contact when isSoftLocked is set to true. This is normally used by Customer Collaboration Platform when a social contact is to be or has been queued to an outside entity.

isInvited

Indicates if the social contact was created as a result of a chat invitation.

Boolean.

Default is false.

If the Social Contact was created as a result of a chat invitation, then isInvited must be set to true.

inviteStatus

The status of chat invitations sent (if any) from this social contact.

String, case-insensitive.

Default is NONE.

Valid values are:

  • NONE (no chat invitations were sent from this social contact)

  • SENT (chat invitations were sent from this social contact)

  • EXPIRED (chat invitations were sent but were not accepted by the customer)

link

References the original source of the social contact.

For email messages, Customer Collaboration Platform creates a link in the following format: 

https://<emailServerAddress>?
u=<toEmailUsername>&f=
<emailFolder>&m=<emailUniqueIdInFolder>
&t=<emailReceivedTimestamp>

The link for email contacts includes the following information:

  • emailServerAddress: The email server that retrieved the contact (the email receive host associated with the feed that retrieved the contact)

  • toEmailUsername: The email user who received the email (the email username associated with the feed that retrieved the contact)

  • emailFolder: The folder that holds the email (the email.receive.folderName associated with the feed that retrieved the contact)

  • emailUniqueIdInFolder: The unique ID that identifies the message in this folder

  • emailReceivedTimestamp: The time that the email server received the message

publishedDate

The social contact published date.

For contacts with sourceType email, this parameter is the date that the email server received the email message.

String.

Leave blank to use the current timestamp or provide a valid Unix timestamp.

refURL

A copy of the URL requested.

replyTemplateRefURL

The reference URL of the reply template. This can be used to retrieve further template details.

Returned by update if the social contact is associated with a feed that has been configured to use a reply template.

replyTemplateURL

The URL of the reply template.

Returned by update if the social contact is associated with a feed that has been configured to use a reply template.

shortUrlId/shortUrlIds

Is a list of short URL Ids which were generated for this social contact.

String.

A short URL is generated by the system when a Customer Collaboration Platform user sends a chat invitation to a customer. The social contact from which the invitation was sent maintains a short URL for each invitation.

sourceType

Is the type of feed this social contact came from: callback, chat, or push.

String.

This is set by Customer Collaboration Platform and cannot be set through the create or update APIs.

status

One of:

  • unread—The default state of a new contact.
  • reserved—Reserved to be handled.
  • handled—This contact has been handled and no further action is required.
  • discarded—This contact does not require a response and is filed in the recycle bin.
  • queued—The contact is in the process of or has been routed to some external entity.
  • draft—A draft response to the contact has been created and saved, but not sent.

String (case-sensitive).

If the submitted and the current status of the social contact are not equal, the submitted status becomes the effective status of the social contact.

The QUEUED status is settable from the API. However, currently, it is only set internally by Customer Collaboration Platform.Customer Collaboration Platform sets the social contact status to QUEUED when a social contact is to be or has been routed to some external entity.

statusReason

The reason why the contact is in the current state.

statusUserId

The user modifying the status to a state other than UNREAD.

The value changes to the user who is currently authenticated against the API.

statusTimestamp

The time stamp of the last state change of the social contact.

Long integer.

Required for PUT.

Important: You must provide the current statusTimestamp of the social contact when you perform an update. If you do not provide the same statusTimestamp as returned from a social contact get request, then the update fails. This mechanism is in place so that two clients cannot update the same social contact at the same time.

The statusTimestamp changes to the current timestamp if the update is successful.

tag/tags

One or more tags to associate with this social contact.

The tags can be new or existing tags. If you include the tags element, but do not include any tag elements, then tags are deleted during an update.

title

The title of the social contact.

String.

Required for POST.

transcriptRefURL

Is a URL to get the chat transcript.

String.

Only applies to contacts where sourceType is chat.