Operating your own Social Server

Access to the social networks is performed exclusively through a Social Server. The extension itself never communicates directly with the individual networks, but only sends requests to the Social Server configured in the extension settings.

By default, the SaaS service operated by fixpunkt is used. Costs may apply for its use.

If you do not want to use this service, you can develop and operate your own Social Server. Afterwards, enter its URL as apiUrl in the extension settings. This chapter describes which interface such a server must provide.

Authentication

All requests to the Social Server are POST requests to the respective endpoint URL. This URL is composed of the configured apiUrl and the path of the endpoint, e. g.:

https://my-server.example.com/api/ + networks/facebook/posts

The parameters are passed as form_params (application/x-www-form-urlencoded). In addition to the endpoint-specific parameters, every request contains the following fields:

Parameter	Description
`version`	Version of the interface. Currently always `2`. This corresponds to the namespace `v2` of the classes mentioned further below.
`auth[username]`	The username stored in the access credentials.
`auth[accesstoken]`	The access token stored in the access credentials.

The server is responsible for verifying auth[username] and auth[accesstoken]. With your own server, you assign these credentials yourself.

Expected response format

The server's response must be a JSON that can be deserialized by the extension, with the help of the extension fixpunkt/fp-social-bridge, into one of the following response objects:

Class	Usage
`Fixpunkt\FpSocialBridge\v2\Response\SocialServerPostsResponse`	Response for a list endpoint (multiple posts).
`Fixpunkt\FpSocialBridge\v2\Response\SocialServerPostResponse`	Response for an endpoint for a single post.
`Fixpunkt\FpSocialBridge\v2\Response\SocialServerErrorResponse`	Response in case of an error.

The individual posts are expected as objects of type Fixpunkt\FpSocialBridge\v2\Data\Post.

Important

The exact structure of these classes – and thus the exact structure of the JSON to be returned – is not documented here, but in the extension fixpunkt/fp-social-bridge. When implementing your server, use that extension as a reference.

Endpoints

For each network, endpoints are needed for reading a list of posts as well as for reading a single post. Each endpoint is described individually below.

The JSON examples each show the complete POST body including the version and auth fields described under Authentication, so they can be copied directly. Depending on the endpoint, the response is expected to be either a list of posts (SocialServerPostsResponse) or a single post (SocialServerPostResponse); the exact format is described in the section Expected response format.

Note

You only need to implement those endpoints whose networks you actually want to use. If an account of an unsupported network is synchronized, only its synchronization fails.

Facebook

`networks/facebook/posts`

Reads the posts of a Facebook page.

POST request to networks/facebook/posts. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "pageId": "Facebook page ID"
}

pageId – ID of the Facebook page from which the posts are read. Corresponds to the channel stored in the account.

Response: List of posts (SocialServerPostsResponse).

`networks/facebook/post`

Reads a single Facebook post.

POST request to networks/facebook/post. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "postId": "Post ID"
}

postId – ID of the post. Corresponds to the ID under which the post was stored when it was read.

Response: Single post (SocialServerPostResponse).

Instagram

Depending on whether the account is operated in Profile or Hashtag mode, either networks/instagram/posts or networks/instagram/hashtag is requested to read the list.

`networks/instagram/posts`

Reads the posts of an Instagram profile (Profile mode).

POST request to networks/instagram/posts. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "pageId": "Instagram profile ID"
}

pageId – ID of the Instagram profile from which the posts are read. Corresponds to the channel stored in the account.

Response: List of posts (SocialServerPostsResponse).

`networks/instagram/hashtag`

Reads posts for a hashtag (Hashtag mode).

POST request to networks/instagram/hashtag. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "pageId": "Instagram profile ID",
    "hashtag": "fixpunkt",
    "mode": "recent_media"
}

pageId – ID of the Instagram profile through which the search is performed. Corresponds to the channel stored in the account.
hashtag – The hashtag to search for (without #).
mode – Search mode for the hashtag. Possible values:
- recent_media – the most recent posts for the hashtag.
- top_media – the top posts for the hashtag.

Response: List of posts (SocialServerPostsResponse).

`networks/instagram/post`

Reads a single Instagram post.

POST request to networks/instagram/post. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "postId": "Post ID"
}

postId – ID of the post. Corresponds to the ID under which the post was stored when it was read.

Response: Single post (SocialServerPostResponse).

Instagram (direct login)

Used for Instagram accounts that are connected through the direct Instagram login instead of a Facebook page. Apart from the missing hashtag search, the endpoints match those of Instagram.

`networks/instagramlogin/posts`

Reads the posts of the connected profile.

POST request to networks/instagramlogin/posts. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "pageId": "Instagram account ID"
}

pageId -- ID of the Instagram account from which the posts are read. Corresponds to the channel stored in the account.

Response: List of posts (SocialServerPostsResponse).

`networks/instagramlogin/post`

Reads a single post.

POST request to networks/instagramlogin/post. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "postId": "Post ID"
}

postId -- ID of the post. Corresponds to the ID under which the post was stored when it was read.

Response: Single post (SocialServerPostResponse).

LinkedIn

Depending on whether the account is operated in Shares or UGC Posts mode, either networks/linkedin/posts or networks/linkedin/ugcPosts is requested to read the list.

`networks/linkedin/posts`

Reads the posts of a LinkedIn page (Shares mode).

POST request to networks/linkedin/posts. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "pageId": "LinkedIn page ID"
}

pageId – ID of the LinkedIn page from which the posts are read. Corresponds to the channel stored in the account.

Response: List of posts (SocialServerPostsResponse).

`networks/linkedin/ugcPosts`

Reads the user-generated-content posts of a LinkedIn page (UGC Posts mode).

POST request to networks/linkedin/ugcPosts. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "pageId": "LinkedIn page ID"
}

pageId – ID of the LinkedIn page from which the posts are read. Corresponds to the channel stored in the account.

Response: List of posts (SocialServerPostsResponse).

`networks/linkedin/post`

Reads a single LinkedIn post.

POST request to networks/linkedin/post. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "postId": "Post ID"
}

postId – ID of the post. Corresponds to the ID under which the post was stored when it was read.

Response: Single post (SocialServerPostResponse).

Youtube

`networks/youtube/videos`

Reads the videos of a YouTube channel.

POST request to networks/youtube/videos. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "channel": "YouTube channel ID"
}

channel – ID of the YouTube channel from which the videos are read. Corresponds to the channel stored in the account.

Response: List of posts (SocialServerPostsResponse).

`networks/youtube/video`

Reads a single YouTube video.

POST request to networks/youtube/video. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "videoId": "Video ID"
}

videoId – ID of the video. Corresponds to the ID under which the video was stored when it was read.

Response: Single post (SocialServerPostResponse).

Wordpress

Depending on the selected mode of the account, one of the following three endpoints is requested to read the list.

`networks/wordpress/posts`

Reads all posts of a Wordpress blog.

POST request to networks/wordpress/posts. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "baseUrl": "https://my-blog.example.com"
}

baseUrl – Base URL of the Wordpress blog from which the posts are read.

Response: List of posts (SocialServerPostsResponse).

`networks/wordpress/postsWithTag`

Reads the posts of a Wordpress blog that are tagged with a specific tag.

POST request to networks/wordpress/postsWithTag. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "baseUrl": "https://my-blog.example.com",
    "tag": "Tag"
}

baseUrl – Base URL of the Wordpress blog.
tag – Tag by which the posts are filtered.

Response: List of posts (SocialServerPostsResponse).

`networks/wordpress/postsFromAuthor`

Reads the posts of a specific author of a Wordpress blog.

POST request to networks/wordpress/postsFromAuthor. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "baseUrl": "https://my-blog.example.com",
    "author": "Author"
}

baseUrl – Base URL of the Wordpress blog.
author – Author by which the posts are filtered.

Response: List of posts (SocialServerPostsResponse).

`networks/wordpress/post`

Reads a single Wordpress post.

POST request to networks/wordpress/post. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "postId": "Post ID",
    "baseUrl": "https://my-blog.example.com"
}

postId – ID of the post. Corresponds to the ID under which the post was stored when it was read.
baseUrl – Base URL of the Wordpress blog to which the post belongs.

Response: Single post (SocialServerPostResponse).

Bluesky

`networks/bluesky/posts`

Reads the posts of a Bluesky profile.

POST request to networks/bluesky/posts. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "clientHandle": "profil.bsky.social"
}

clientHandle – Handle of the Bluesky profile from which the posts are read. Corresponds to the channel stored in the account.

Response: List of posts (SocialServerPostsResponse).

`networks/bluesky/post`

Reads a single Bluesky post.

POST request to networks/bluesky/post. The body is transmitted as form_params (application/x-www-form-urlencoded):

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    },
    "uri": "at://…"
}

uri – AT URI of the post. Corresponds to the ID under which the post was stored when it was read.

Response: Single post (SocialServerPostResponse).

Accounts

`accounts`

Lists all accesses that the user has connected on the server, grouped by network. The backend uses this endpoint for the channel selection next to The Channel; it is optional -- without it the channel simply has to be entered by hand.

POST request to accounts. The body is transmitted as form_params (application/x-www-form-urlencoded) and needs no arguments beyond the ones described under Authentication:

{
    "version": 2,
    "auth": {
        "username": "Your username",
        "accesstoken": "Your access token"
    }
}

Response: List of accesses (SocialServerAccountsResponse). The accounts key is an object whose keys name the network and whose values are lists of accesses:

{
    "type": "Fixpunkt\\FpSocialBridge\\v2\\Response\\SocialServerAccountsResponse",
    "version": 2,
    "accounts": {
        "Fixpunkt\\FpSocialServer\\Networks\\Facebook\\Connector": [
            {
                "uid": 12,
                "network": "Fixpunkt\\FpSocialServer\\Networks\\Facebook\\Connector",
                "networkKey": "facebook",
                "networkName": "Facebook",
                "displayName": "Example Organization",
                "username": "100000000000001",
                "email": "office@example.com",
                "expires": null,
                "expired": false,
                "channels": [
                    {"id": "200000000000001", "name": "Example Page"}
                ]
            }
        ]
    }
}

networkKey -- short form of the network. The extension maps facebook, instagram, instagramlogin and linkedin to its own account types; accesses of any other network are ignored.
channels[].id -- the value that is written into the channel of an account, and that is expected back as pageId by the endpoints above.
channels[].name -- the value that is written into the label.
expires -- expiry date of the access, or null for networks whose access keys do not expire. expired says whether it has already passed.

Note

Never return the access keys themselves here. The channels are meant for display and for filling in the account, not for authentication.

Error handling

If an error occurs on the server, you have two options:

You respond with a JSON that can be deserialized into a SocialServerErrorResponse.

You respond with an HTTP error status (4xx) and a body in the following form:

{
    "error": {
        "message": "Error description",
        "code": 1652117377
    }
}

In both cases, message and code are evaluated by the extension and displayed in the backend as a synchronization error.

Tip

If a single post was deleted in the network, return an error with the code 1585047168. The extension then marks the corresponding post as deleted at the origin.