# Snapchat

Publish Stories, Saved Stories and Spotlight videos to a Snapchat Public Profile and read views, reach and shares. In beta.

Snapchat publishing goes to a Public Profile: a Story that lasts 24 hours, a Saved Story that stays on the profile, or a Spotlight video in Snapchat's public feed. You use the same `POST /v1/posts` call with the platform id `snapchat`.

> **Snapchat is in beta:**
> 
> Snapchat connections are not open to every workspace yet. A workspace without access gets `403` with code `PLATFORM_BETA_RESTRICTED` when it asks for a connect URL, before any Snapchat screen appears. Retrying does not help. Write to support@pozy.ai if you need Snapchat, and branch on `code`, not on the message text.

## What you can do

| Feature | Supported | Where |
| --- | --- | --- |
| Story (24 hours, no caption) | Yes | [Post types](#post-types) |
| Saved Story (permanent, with a title) | Yes | [Post types](#post-types) |
| Spotlight (permanent video, with a description) | Yes | [Post types](#post-types) |
| Scheduling | Yes | [Scheduling](https://pozy.ai/docs/publishing/scheduling) |
| Analytics | Views, reach, shares | [Analytics](#analytics) |
| DMs, comments | No | Snapchat's messaging API is closed to third-party apps |
| Text-only posts, carousels | No | Every post needs exactly one image or video |

## Connect

Only a Snapchat Public Profile (Person, Business or Official) can publish through the API. A regular account cannot.

Request a connect URL with the platform `snapchat` and send the user to `authUrl`. After they authorize, they choose which Public Profile to connect. Pozy hosts that picker by default. With `headless=true` you build it yourself with [List Snapchat profiles](https://pozy.ai/docs/api/listSnapchatProfiles) and [Select Snapchat profile](https://pozy.ai/docs/api/selectSnapchatProfile). See [Hosted connect](https://pozy.ai/docs/connect/hosted-connect) and [Headless connect](https://pozy.ai/docs/connect/headless).

```bash
curl "https://api.pozy.ai/v1/connect/snapchat?profileId=66a1f0c2a4b9d3e8f1a2b3c4&redirect_url=https://app.example.com/connected" \
  -H "Authorization: Bearer $POZY_API_KEY"
```

## Post types

`platformSpecificData.contentType` picks the format. It defaults to `story`.

| `contentType` | What it publishes | Lifetime | How `content` is used |
| --- | --- | --- | --- |
| `story` | A snap in the profile's Story | 24 hours | Ignored. Stories have no caption |
| `saved_story` | A permanent story on the Public Profile | Permanent | Title, up to 45 characters |
| `spotlight` | A video in the Spotlight feed (video only) | Permanent | Description, up to 160 characters including hashtags |

```bash cURL
curl -X POST https://api.pozy.ai/v1/posts \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Behind the scenes at the shoot #bts",
    "mediaItems": [{ "type": "video", "url": "https://pozy.ai/media/bts-vertical.mp4" }],
    "platforms": [{
      "platform": "snapchat",
      "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
      "platformSpecificData": { "contentType": "spotlight" }
    }],
    "publishNow": true
  }'
```
```ts Node
const res = await fetch("https://api.pozy.ai/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: "Behind the scenes at the shoot #bts",
    mediaItems: [{ type: "video", url: "https://pozy.ai/media/bts-vertical.mp4" }],
    platforms: [{
      platform: "snapchat",
      accountId: "66b2e19d8c3f5a7e9d0b1c2d",
      platformSpecificData: { contentType: "spotlight" },
    }],
    publishNow: true,
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.post.status);
```
```python Python
import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/posts",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "content": "Behind the scenes at the shoot #bts",
        "mediaItems": [{"type": "video", "url": "https://pozy.ai/media/bts-vertical.mp4"}],
        "platforms": [{
            "platform": "snapchat",
            "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
            "platformSpecificData": {"contentType": "spotlight"},
        }],
        "publishNow": True,
    },
)
print(resp.json()["post"]["status"])
```

For a Story, drop `contentType` (or set `"story"`) and send an image or a video. For a Saved Story, set `"saved_story"` and keep `content` under 45 characters.

| Field | Type | Notes |
| --- | --- | --- |
| `contentType` | `story`, `saved_story` or `spotlight` | Default `story` |

## Media requirements

Every post carries exactly one image or one video, in vertical 9:16. Files outside these limits are rejected, not compressed.

| Images | Requirement |
| --- | --- |
| Formats | JPEG, PNG |
| Max size | 20 MB |
| Recommended | 1080 x 1920 px (9:16) |

| Videos | Requirement |
| --- | --- |
| Format | MP4 |
| Max size | 500 MB |
| Duration | 5 to 60 seconds |
| Minimum resolution | 540 x 960 px |
| Recommended | 1080 x 1920 px (9:16) |

Snapchat requires media to be encrypted before upload. Pozy does that for you, so you send a normal URL. Upload through [Media](https://pozy.ai/docs/publishing/media) for a URL that qualifies.

## Limits

| Limit | Value |
| --- | --- |
| Media per post | Exactly 1 |
| Saved Story title | 45 characters |
| Spotlight description | 160 characters, hashtags included |
| Spotlight media | Video only |

Not available through Snapchat's API: AR lenses and filters, Snap Map, Snapchat sounds, collaborative stories, friends' stories, DMs and comments. Snapchat ads are not part of the Snapchat connection.

## Analytics

[Get post analytics](https://pozy.ai/docs/api/getAnalytics) with `platform=snapchat` returns:

| Metric | Field |
| --- | --- |
| Views | `views` |
| Unique viewers | `reach` |
| Shares | `shares` |

`likes`, `comments` and `saves` are always `0`, because Snapchat has none of them. Screenshot counts and completion rates are not exposed.

## Inbox

Snapchat accounts do not appear in the [Inbox](https://pozy.ai/docs/inbox). Snapchat does not give third-party apps access to DMs or snap replies.

## Errors you may see

| Error | Cause | Fix |
| --- | --- | --- |
| `403` `PLATFORM_BETA_RESTRICTED` | Snapchat is not enabled for this workspace | Contact support@pozy.ai |
| "Public Profile required" | The account has no Public Profile | Create one in Snapchat and choose it while connecting |
| "Media is required" | No media on the post | Add one image or video |
| "Only one media item supported" | More than one media item | Send a single file |
| Video rejected | Duration, format, resolution or size is out of range | Check 5 to 60 seconds, MP4, at least 540 x 960 px, under 500 MB |
| "Title too long" | Saved Story `content` over 45 characters | Shorten it |
| "Description too long" | Spotlight `content` over 160 characters | Shorten it, hashtags included |

[Errors](https://pozy.ai/docs/getting-started/errors) covers the error format.

## Endpoints

| Endpoint | What it does |
| --- | --- |
| [`GET /v1/connect/{platform}`](https://pozy.ai/docs/api/getConnectUrl) | Get OAuth connect URL |
| [`GET /v1/connect/snapchat/select-profile`](https://pozy.ai/docs/api/listSnapchatProfiles) | List Snapchat profiles |
| [`POST /v1/connect/snapchat/select-profile`](https://pozy.ai/docs/api/selectSnapchatProfile) | Select Snapchat profile |
| [`POST /v1/posts`](https://pozy.ai/docs/api/createPost) | Create post |
| [`GET /v1/analytics`](https://pozy.ai/docs/api/getAnalytics) | Get post analytics |

## Webhook events

| Event | When it fires |
| --- | --- |
| [`post.published`](https://pozy.ai/docs/webhooks/events#post-published) | Post published. |
| [`post.failed`](https://pozy.ai/docs/webhooks/events#post-failed) | Post failed. |
| [`post.platform.published`](https://pozy.ai/docs/webhooks/events#post-platform-published) | Post platform published. |
| [`post.platform.failed`](https://pozy.ai/docs/webhooks/events#post-platform-failed) | Post platform failed. |
| [`post.platform.deleted`](https://pozy.ai/docs/webhooks/events#post-platform-deleted) | Post platform deleted. |