Skip to main content
GET
获取某个消息平台的消息或会话。 不同社交网络的检索时间有所不同。在 Facebook、Instagram 和 WhatsApp 上,消息可通过 Ayrshare 实时获得。在 X/Twitter 上,查看新消息更新最多有 3 分钟延迟。若你需要实时访问 X/Twitter 消息,请联系支持团队了解 Enterprise Plan 的详情。
**响应缓存:**对于 Facebook 和 Instagram,响应缓存 60 秒。对于 X/Twitter,响应缓存 15 秒,以更好地支持轮询。WhatsApp 直接读取已通过 Meta webhook 收到的消息,因此在 Ayrshare 处理完 webhook 后,新收到的消息即可显示。响应中仍会包含 lastUpdated 与 nextUpdate 元数据。
对于 Facebook 和 Instagram,首次消息历史检索仅限于最近 20 条消息。详情请参阅 Facebook 和 Instagram 的消息历史检索 部分。
WhatsApp 会话通过通信对象的电话号码进行标识(仅数字,E.164 格式且不含前导 +)。已存储的出站消息可能包含一个取值为 sent、delivered、read 或 failed 的 status 字段。
目前通过 发送消息 发送的 WhatsApp 消息不会加入 Get Messages 的历史记录。通过 webhook 收到的入站 WhatsApp 消息会被存储,并可在此处返回。

Header Parameters

Path Parameters

string
必填
用于获取消息的平台:facebook、instagram、twitter、whatsapp

Query Parameters

string
默认值:"active"
必填
返回活跃会话或已归档会话。取值:active 或 archived。
string
仅返回指定的会话。
string
仅返回单一方向的消息。取值:sent 或 received。省略则同时返回两者。
boolean
默认值:false
返回会话而非消息。仅返回一页会话——请跟随 meta.pagination.next 获取其余部分。若为 true,将忽略 conversationId。
当 conversationsOnly=true 时,会话详情会在 converstationsDetails 中返回。此拼写是当前 API 响应的一部分。
integer
消息与会话列表的每页大小:1 到 100 的整数,默认值和最大值均为 100。在 X/Twitter 上,limit 还决定你读取哪一组消息。省略它将分页读取已存储的消息,这与其他所有平台一致,并且会应用 status、action 和 conversationsOnly。提供它则改为通过 X 自己的游标分页读取 X 的实时时间线,该方式不应用上述三个筛选条件。该选择仅由首次请求决定。一旦开始跟随游标,就由游标决定:已存储消息的游标即使你传入 limit 也会继续返回已存储的消息,而 X 的游标即使你省略 limit 也会继续返回实时时间线。分页过程中无法在两者之间切换。
string
来自 meta.pagination.next 的不透明游标。请使用相同的用户配置、平台和筛选条件将其作为 next 传入。只要 meta.pagination.hasMore 为 true 就继续,即使筛选后的页面较短或为空。后续请求可省略 limit(默认 100);在 X/Twitter 上,游标本身已记录它来自哪一组,因此传入或省略 limit 都不会把你切换到另一组。

获取下一页

从 GET /api/messages/instagram?limit=100 开始。要继续获取,请对返回的 meta.pagination.next 值进行 URL 编码,然后发送 GET /api/messages/instagram?limit=100&next=<opaque cursor>。参数名是 next,而不是 cursor。全程保持相同的 Profile-Key 和查询筛选条件。 请通过检查 meta.pagination.hasMore 而不是结果数量来决定何时停止。由于每次请求只扫描有限范围的历史记录,带筛选条件的请求可能返回少于 limit 条的结果,或返回带有后续游标的空页。已存储历史中的消息按最新在前排序,并以文档 ID 决定并列顺序。会话列表按文档 ID 排序。分页并不是一个冻结的快照:从第一页重新开始时会出现新消息,而会话状态的变化也可能改变筛选后的结果。 现有消息字段和 converstationsDetails 拼写保持不变。此前期望通过一次请求获得完整列表的集成——无论是消息还是会话、无论在哪个平台上——都必须跟随后续游标;不支持将 limit 提高到 100 以上。