SCG platform supports 2 ways of specifying media content for messaging and voice calls.
- Creating an attachment resource and referencing it in the API request via an unique attachment resource ID.
- Specify an inline media URL that references media content in an external storage.
Most common use cases for media content would be
- Attachment of a image or document as message content.
- Media content to support playing an audio or a video to enhance the experience.
The following channels support the use of attachments
- MMS
- Push
- Voice
How to create re-usable media content ?
Step 1 : Create an attachment resource.
Curl command:
curl –location --request POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/attachments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [TOKEN]' \
--data-binary '{"name":"Image Attachment test","type":"image/jpeg","filename":"car front.jpg"}'
Response:
{"id":"9LknkKCDx63jewwqgtFjA4"}
Step 2 : Create an access token for the above attachment. Reference the unique attachment resource identifier returned in Step 1.
Curl command:
curl -X POST 'https://api.syniverse.com/scg-external-api/api/v1/access_tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [TOKEN]' \
--data-binary '{"resource": "ATTACHMENT","resource_id":"9LknkKCDx63jewwqgtFjA4"}'
Response:
{"id":"oQFV20p315B9AHAuJUele4"}
Step 3 : Upload the attachment as multipart form data. Specify the access token generated in Step 2.
Curl command:
curl --location --request POST 'https://api.syniverse.com/scg-attachment/api/v1/messaging/attachments/oQFV20p315B9AHAuJUele4/content' \
--header 'Content-Type: application/octet-stream' \
--header 'Authorization: Bearer [TOKEN]' \
--data-binary '@/c:/tmp/car front.jpg'
Once the attachment is successfully created and the media is uploaded, the unique attachment resource identifier can be referenced when sending messaging or voice API request.
How to reference media content from an external storage provider ?
When sending API requests for messaging or voice calls, external media content can be referenced as a media URL. Please note that redirected URLs are not supported. The value specified for the Media URL must be an absolute URL that is pointing to the specific content you intend to send using the media URL
Attachment Retention Policy
Any attachments uploaded to the SCG platform will be archived and would not be available for use 2 years from the time of the initial upload.
Uploading Attachments via the SCG UI
Attachments can be managed via the Voice and Messaging Console. Log into your account using valid credentials and navigate to the attachments section using the 'Attachments' menu under the left navigation (under Messaging). For detailed information click here.
Best Practices
- Create attachment resources for re-usable media content as it is easy to reference it in the API requests.
- Media content that is message context specific (one-time use) should be handled via media URLs.
Supported Media Requirements for Channels
Every channel enabled by the omni-channel API has different requirements in terms of what type of media are supported, how large the content size can be and how many attachments can be specified for a given message or voice call.
0 Comments